Custom Firmware Compilation

Getting Started with Custom Firmware Compilation

Overview of Custom Firmware for Advantech Routers

Compiling custom firmware for Advantech routers involves modifying or rebuilding components of the router's operating system (ICR-OS). This can range from recompiling individual open-source utilities to, in theory, building a more comprehensive firmware image. This process is intended for advanced users who understand the implications and risks involved.

It is important to note that while it might be technically possible to build a complete firmware image using the provided sources, the router hardware will typically reject firmware images that are not digitally signed by Advantech. Therefore, the primary focus of custom compilation for end-users is often the modification or replacement of individual open-source components.

Prerequisites and Essential Knowledge

To embark on custom firmware compilation or modification of its components, certain prerequisites are essential:

Operating System: A 64-bit Linux-based operating system is necessary for the build environment. This can be a dedicated physical machine or a virtual machine.
Technical Skills: Familiarity with the Linux command line, basic C/C++ programming concepts (if modifying source code), and an understanding of build systems (like Make) are highly beneficial.
Hardware Access: Access to the target Advantech router for testing and deployment is required.

Users are expected to have the necessary expertise to manage their Linux development environment.

Obtaining Firmware Source Code and Build System Components

All necessary development resources, including source code for open-source components and toolchains, are typically available through Advantech's Bitbucket repositories.

If your goal is to rebuild or modify an open-source component included in ICR-OS, you must first download the source code corresponding to your specific router firmware version. This can be found on the Advantech ICR Source Code page. To determine your firmware version, navigate to the router's web interface, select General from the left menu, and check the System Information page. The firmware version follows a major.minor.patch format (e.g., 6.1.5). The corresponding source archive will typically be named similarly (e.g., firmware-6.1.5-src.tar).

The essential first step for any C/C++ development, including modifying firmware components, is to obtain and set up the appropriate cross-compiler for your target router platform. This enables you to generate executable binaries on your development machine that can run on the router. Details on acquiring and setting up the cross-compiler are provided in the SDK chapter (within the Router Apps part of this manual).

Preparing the Build Environment

Setting Up the Development Host System

The instructions for setting up the build environment and its prerequisites have been validated on Ubuntu and Debian distributions. If you are using an RPM-based distribution (such as Fedora, which is also suitable), you will need to adapt the package installation commands to use your system's package manager (e.g., dnf or yum). Package names for dependencies might also differ slightly across distributions.

Setting Up the Cross-Compilation Toolchain

As mentioned in the previous section, a cross-compiler specific to your target Advantech router platform is crucial. This toolchain allows your development host (e.g., an x86-64 Linux machine) to compile code that will execute on the router's different processor architecture (typically ARM-based).

Please refer to the SDK chapter for detailed instructions on downloading, installing, and configuring the appropriate cross-compiler toolchain provided by Advantech. Ensure the toolchain's binaries are accessible in your system's PATH environment variable.

Configuring the Build System

Tips

This section would typically describe how to use tools like menuconfig or similar configuration interfaces if provided with the firmware source package to select components, features, and target platforms before starting the build process.

Understanding the Build Directory Structure

Tips

This section would describe the layout of the firmware source code directory, highlighting important subdirectories such as those containing package sources, kernel sources, toolchain integration, build scripts, and output locations for compiled binaries and images.

Building the Custom Firmware Image Components

The Firmware Build Process: Step-by-Step

Tips

Detailed build instructions for specific components are usually provided within the README file included in the downloaded source code archive for that component or the overall firmware source package. Generally, this involves navigating to the correct source directory and using make with appropriate targets.

Building and Integrating Open-Source Components

When rebuilding or modifying an open-source component from the ICR-OS sources:

Locate the Component: Identify the specific component's source directory within the downloaded firmware source archive.
Consult README: Detailed build instructions for individual components are typically provided within a README file in their respective source directories or in a general README for the entire source package.
Advantech Modifications: Any modifications made by Advantech to the original open-source components are usually supplied as distinct patch files within the archive. This allows for easy identification and understanding of the changes applied by Advantech.
Compilation: Follow the provided instructions to compile the component using the prepared cross-compilation toolchain. This usually involves standard commands like make.

The output will be the recompiled binary, library, or other files associated with that component.

Customizing the Linux Kernel (If Applicable)

Tips

Modifying the Linux kernel is a highly advanced task. If undertaken, it would involve obtaining the kernel source specific to the router, configuring it using kernel configuration tools (e.g., make menuconfig within the kernel source directory), compiling it with the cross-compiler, and then integrating the new kernel image. Replacing the kernel is extremely risky and can easily lead to an unbootable device.

Generating and Locating Firmware Image Files

When you recompile individual open-source components, the output is typically the specific binary or library file (e.g., an executable utility, a .so shared library). These files will be located in the build output directory specified by the component's build system, often within a subdirectory related to the target architecture.

As stated earlier, building a complete, digitally signable firmware image for direct flashing via standard update mechanisms is generally not feasible for end-users due to signature requirements. The process described here focuses on replacing individual, uncritical components.

Troubleshooting Common Build Issues

Tips

Common build issues include:

Incorrectly configured cross-compiler path.
Missing development libraries or tools on the host system (install them using your distribution's package manager).
Incompatibility between the source code version and the toolchain.
Typos in Makefiles or configuration scripts if modifications were made.

Always check the error messages carefully and consult the README files.

Installing and Managing Custom Firmware Components

Methods for Installing Built Firmware Components

After successfully building a component according to the instructions in the source archive's README file, the resulting binary or library files must be copied onto the target router's filesystem. This typically involves overwriting the original files. This process usually requires root access to the router, commonly achieved via SSH.

General Procedure (Non-S1 Routers):

Ensure you have root access to the router (e.g., via SSH).
Identify the location of the original component on the router's filesystem.
It is highly recommended to back up the original file before overwriting it.
Use a secure copy tool (like scp) to transfer the newly built file from your development machine to the appropriate location on the router, overwriting the original.
Verify file permissions and ownership of the newly copied file match the original.
Reboot the router or restart the relevant service for the changes to take effect (depending on the component).

S1 Router Line Devices:
For S1 Router line devices, which feature a read-only root filesystem, installing custom components by directly overwriting files in system directories is generally not possible. Instead, such components often need to be packaged into a Router App that utilizes an overlay mechanism to present the modified files to the system. This is described in more detail in the chapter on Extending the Read-Only Root Filesystem.

Initial Boot-up and System Verification

Tips

After replacing a component and rebooting (if necessary):

Check system logs for any new errors.
Test the functionality related to the replaced component.
If a utility was replaced, try running it from the command line with relevant options.

Important Note on Running Custom Firmware Components

Modifying or replacing standard firmware components with custom-built versions carries significant risks and consequences. Consider the following points carefully:

Even minor modifications to standard utilities or libraries can have unintended side effects, potentially disrupting system stability, breaking features, or causing router malfunctions.
Advantech CZ R&D bears no responsibility for any issues, damages, or malfunctions resulting from the use of custom or modified firmware components. Such modifications may invalidate product certifications and guarantees.
An Advantech router is a complex system comprising hardware, firmware (software), and certifications. Altering any of these layers results in a product that is fundamentally different from the one originally manufactured and certified by Advantech.
Firmware components built solely from the provided open-source components might interact differently if they depend on Advantech's proprietary software which is not part of the open-source release. This means certain features may be affected, or full hardware support related to that component might be compromised.
Running custom or modified firmware components voids the device warranty if such modifications are found to be the cause of a malfunction.
- If modifications lead to non-compliance, all certifications listed on the device label and in the Declaration of Conformity could be considered invalid for that modified state. Telecommunication certification labels (e.g., PTCRB, GCF, RCM, FCC/IC) are tied to the specific certified firmware and hardware configuration.
- Improper hardware handling resulting from firmware component modifications (e.g., incorrect power sequencing for peripherals due to a modified driver or utility) can shorten the device's lifespan or cause permanent hardware damage.
- If you intend to distribute devices running your custom firmware components, and these significantly alter the product's certified behavior, the Advantech labels may no longer fully represent the product. Please contact Advantech business representatives to discuss options if extensive modifications are planned for commercial redistribution.
Custom firmware components are not supported by Advantech Czech s.r.o. If a device becomes unbootable or unusable due to such modifications (e.g., corrupted critical library, damaged MRAM data due to a faulty custom utility), Advantech support will not cover repairs under warranty. Attempting repairs will incur service fees.
Uploading custom firmware images (if a full image build was attempted and is possible to flash) to devices running standard ICR-OS (v3 generation and later) will trigger a warning about the missing digital signature. Proceeding past this warning is done at your own risk and confirms acceptance of the warranty voidance implications. (Note: Digital signature verification for full firmware images applies primarily to v3 and later generation devices.)

Exercise extreme caution when replacing system components: replacing critical system components, particularly the Linux kernel or essential libraries like libc, can potentially render the device unbootable ("bricked"), often without a straightforward recovery method. Modifying firmware components is done entirely at your own risk.

Post-Installation Troubleshooting

Tips

If issues arise after installing a custom component:

Revert Changes: If possible, restore the original backed-up component.
Check Logs: Examine system logs (Status → System Log in the web interface, or via dmesg/logread on the console) for error messages related to the modified component.
Serial Console: Access via a serial console can provide boot messages and diagnostic information even if the network or SSH is unavailable.
Safe Mode/Recovery: Familiarize yourself with any safe mode or firmware recovery procedures applicable to your router model (if available) before making critical changes.