##############################################################
OSS components of the TG1682(XB3) HOME GATEWAY
FW Version 10.1.27B
##############################################################
README.txt - This file explains the OSS package contents and how to build.
== CONTENTS==
Overview
Package Info
Open Source Toolchain
Build Environment
System Requirements for the Build Computer
Installation
Build Instructions
End
== Overview ==
The ARRIS TG1682 is an advanced DOCSIS 3.0 residential voice gateway that combines 24DS channel bonding, two analog voice lines, a 4-port Gigabit Router, MoCA 2.0 for superior in home coverage, and a Dual Band 802.11ac wireless access point into a single integrated device.
This package contains the files used in the 10.1.27B firmware version on TG1682 that
are open source and meant for re-distribution to the community.
== Package Info ==
A brief description of the files included in the TG1682_10.1.27B_part1.tar.gz package is shown below:
README.txt : This README file.
buildserversetup.sh : The auto-install script.
packages.sh : An auxiliary shell script, executed by buildserversetup.sh,
to install packages specified in package.list.
package.list : Used to specify which additional software packages to install.
install.config : Used to specify build configuration options.
workspace.tar.gz : The build workspace tarball, containing additional open source
software and build scripts.
A brief description of the files included in the TG1682_10.1.27B_part2.tar.gz package is shown below:
It contains the necessary tarballs which is required for compiling the re-distribution package
== Open Source Toolchain ==
The auto-install script will install all software packages required to build in a yocto
environment. The yocto environment will build the toolchain, so you do not build the toolchain
independently of the rest of the packages. That is, the open source packages are dependent
on the toolchain for both Atom and Arm builds.
== Build Environment ==
Yocto/BitBake tools are used to build the platform code in this re-distribution package.
Yocto version 1.6 (Daisy) is the recommended version to use when building this package.
Refer to https://www.yoctoproject.org/docs/1.6/mega-manual/mega-manual.html for documentation
on the Daisy release of Yocto.
The build uses bash. Therefore, the build machine setup instructions and auto-install script
set bash as the defult shell.
The build environment uses Git extensively. As such, a name and email address is required
by git to perform some of the operations, because some of the components fetched are git
repos. The name and email address is not shared with any
entity when setting up the build machine. They are merely saved to the git configuration and
used as such to satisfy Git's requirements for those operations for which it needs that
information. If you already have a Git name and email, you may use those. However, there is
no reason you could not use an alias for both of these.
== System Requirements for the Build Computer ==
Using Yocto/BitBake to build the open source software requires more resources from the
build computer than building the software from the legacy tools. It requires more memory,
more space on the file system, and more time to build the kernel and rootfs images.
These are the reasons for the increased resources:
- The open source elements (kernel, drivers, applications, etc.) are built from scratch,
with a few exceptions, using source code from their respective open source Git
repositories that are available online.
Moreover, for each workspace, the tool chain and other required native binaries are built
before the platform open source packages. The build computer requires more system resources
to build all of these components.
- The Yocto/BitBake system permits the user to configure the parallel tasks needed to run
concurrently during the BitBake build process. These concurrent tasks can reduce the
build time, depending on the number of cores available in the user's build computer,
but it puts a heavier load on the available memory and the file system.
- The Yocto/BitBake build system uses a different toolchain, which are faster or slower,
depending on the details of the components built. The BitBake recipes offer a higher
level of build abstraction, such as retrieving missing components automatically from
the source repositories over the network, but has a higher build overhead. This extra
overhead is usually small, but if the network connection is slow it becomes significant.
The system requirements to build the open source re-distribution package with the
Yocto/BitBake tools include:
Memory
The build computer typically requires 4 GB of main memory for each instance of a running
BitBake build. 8 GB of main memory is recommended.
File Space
The build computer must have a minimum of 80 GB of file storage space to run a single
instance of the BitBake build with no task parallelism configured in the local.conf file.
Elapsed Time
The time required to complete a build from scratch depends on the HW platform used,
including the number of available cores, free memory, and the available file space.
Elapsed time for a build from scratch can vary from under an hour to more than five
hours. After the initial build is complete, incremental builds occur much faster
because most of the components do not need to be rebuilt.
Network
While a network connection (i.e., Internet) is required to prepare the environment
(i.e., install required software packages) for the build machine, no netowrk connection
is required to build the components for this open source redistribution package. That is,
once your build machine has been fully set up, you may go offline to perform the build.
== Installation ==
The following installation and build instructions have been verified on an Ubuntu
14.04.5 LTS 64-bit host. Make sure you have an Internet connection to create the host
environment setup. For your convenience, a couple of shell scripts are provided, with
an associated package.list file which specifies the additional software packages to
install on the build machine. When configuring a build machine from scratch, these
scripts should simplify the environment installation process by automating the steps
involved. To use the scripts, download/copy them to a folder on the build machine.
Note that you must have sudo access to install the additional software packages.
* OS Installation
-----------------------------------
Download and install Ubuntu 14.04.5 LTS 64-bit OS. We recommend, when you install Ubuntu,
that you select the checkbox to "Download updates while installing." If you are asked if
you would like to upgrade to a newer version of Ubuntu after installation has completed,
select "Don't Upgrade."
"uname -a" command output:
---------------------------
Linux ubuntu 4.4.0-31-generic #50~14.04.1-Ubuntu SMP Wed Jul 13 01:07:32 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux
* Yocto-related Package Installation
-----------------------------------
-- Unpack the main tarball --
1) Download the TG1682_10.1.27B_part1.tar.gz file to a location in user file space (in
which the current user has read-write-execute permissions).
2) Change to the directory where "TG1682_10.1.27B_part1.tar.gz" was downloaded.
3) Untar the contents using the command: tar -xzf TG1682_10.1.27B_part1.tar.gz
This will create a directory named TG1682_10.1.27B_part1.
4) Change to the TG1682_10.1.27B_part1 directory. In it you will see the following:
README.txt (this file)
buildserversetup.sh
install.config
packages.sh
package.list
workspace.tar.gz
5) Download the TG1682_10.1.27B_part2.tar.gz file to a location in user file space (in
which the current user has read-write-execute permissions).
6) Change to the directory where "TG1682_10.1.27B_part2.tar.gz" was downloaded.
7) Untar the contents using the command: tar -xzf TG1682_10.1.27B_part2.tar.gz
This will create a directory named TG1682_10.1.27B_part2, which will have mandatory
tarball to compile the re-distribution package.
-- Automated Installation and Setup --
Steps to complete the installation of the Yocto-related packages using
the scripts are as follows:
1) Copy the following four files to a location on your build machine where you have
read-write-execute permission (home folder should be fine):
buildserversetup.sh
packages.sh
package.list
install.config
NOTES:
Alternately, you may simply change to the directory where these files already
reside. They must all exist in the same folder in which the buildserversetup.sh
script is run. You must have Internet access while running the script.
The package.list file contains a list of all the packages (required by
Yocto/BitBake and ARRIS, as well as some recommended packages) to be installed on
the build machine. These packges are automatically installed when the user
invokes the buildserversetup.sh script. The script logs various steps to
buildserversetup.log as it progresses through the installation.
2) If the scripts (with .sh file extension) are not already executable, make them so
using the chmod command.
3) If not already in the script directory, change to that directory.
4) Execute the buildserversetup.sh script with no parameters as follows:
./buildserversetup.sh
NOTES:
The script will abort if there are any errors in your configuration.
This is an interactive script, so you will go through a series of several prompts
asking if you wish to continue. It will also prompt you for your Git name and
email address, which are required. At the interactive prompts, the default
answer is indicated by a capital letter. To select the default answer, you may
simply press "enter." Otherwise, select the desired letter and press "enter."
5) When the script successfully completes, you will see the message "Installation
completed!"
NOTES:
If you see any errors in the installation of software packages, such as packages
being held or kept (reported by pkgProblemResolver::Resolve), you might want to
try to resolve them before proceeding. You may follow the advice offered here:
https://superuser.com/questions/1107334/apt-says-packages-have-been-kept-back-what-to-do,
where you alternately issue the following two commands until there are no remaining
upgradeable packages.
sudo apt list --upgradable
sudo apt-get install -y <package-to-upgrade>
Otherwise, you may need to installed the failed packages manually.
If you do not end up with the minimum version of Git, then you will need to remove Git
with the following command:
sudo apt-get autoremove --purge git
and then perform the following steps to install the latest version:
sudo apt-add-repository ppa:git-core/ppa
sudo apt-get update
sudo apt-get install git
The buildserversetup.sh script may be re-run as desired.
== Workspace Setup ==
1) From your home folder, create a subfolder named "workspaces" as in the following
example:
mkdir workspaces
2) Copy the workspace.tar.gz file to the "workspaces" subfolder.
3) Change to the "workspaces" folder and untar the workspace.tar.gz file using
the following command:
tar -xzf workspace.tar.gz
A folder named "workspace" will be created, containing all the source and recipes.
It is highly recommended to delete the workspace.tar.gz file from the workspaces folder.
This ensures disk space usage for the build stays below 80GB.
4) Change to the TG1682_10.1.27B_part2 directory and copy all the tarballs to the "workspace/downloads" directory
using the below command.
cp * workspace/downloads
== Build Instructions ==
* Before you build the first time in any workspace
-----------------------------------
A note about the "downloads" location:
A yocto build, as configured in this delivery, will automatically populate the
"downloads" location with tarballs, repos, and files the first time a build is
conducted. Thereafter, the fetch tasks will take less time for subsequent
builds. If you delete files from this location, those fetch tasks will have to
be repeated. Do NOT delete anything under the "git2" symlink under "downloads,"
as the build scripts require these files.
* Building the open source software/firmware
-----------------------------------
1) In the workspace folder, Execute the following command to build atom components.
MACHINE=arrisxb3atom source meta-rdk/setup-environment build-atom
bitbake comcast-broadband-dev-image
Once build completed go back to workspace folder and execute the following command to build arm components.
MACHINE=arrisxb3arm source meta-rdk/setup-environment build-arm
bitbake comcast-broadband-dev-image
Note:
You will see various warnings in the build output. You should ignore these.
2) The results of the build will be in the build-atom and build-arm folders.
Redistributed packages file are present in the following directories.
build-atom/tmp/work/arrisxb3atom-rdk-linux/
build-atom/tmp/work/core2-32-rdk-linux/
build-arm/tmp/work/arm1176jzstb-rdk-linux-uclibceabi/
build-arm/tmp/work/arrisxb3arm-rdk-linux-uclibceabi/
3) During some scenarios, if the build is interrupted, it might fail as proper clean might not have happened. Please follow the below instructions
- Clean the recipe and rebuild again (e.g. bitbake -c cleansstate <recipe-name>; bitbake <recipe-name>) (OR)
- remove the build directories (e.g. build-atom / build-arm in this case), sstate-cache and retrigger the build again.
= END =
Download Latest Version
TG1682_10.1.27B_part2.tar.gz (4.7 GB)
