If you want to (re-)build an opensource component of the ICR-OS, you need to do two things prior to that:
- Prepare build environment according to Preparing build environment page.
- Fetch source code matching the version of your firmware (or just take the most recent one) from the source code page.
- Note that there can be more source code present on the page than just the source code for the ICR-OS itself.
- Also, artifacts concerning source code, in general, may be listed on the source code page.
- To find out which version of ICR-OS is running on your router, please look under the System Information paragraph on the default page of the router. You can also access the default page by clicking on the General item in the left menu. Under the System Information (located at the bottom of the default page) the first item should read Firmware Version. All released (non-beta) versions come in the format of three digits split by dots - a form that is described by common words: major.minor.patch level. A matching firmware source code archive file name for firmware version 6.1.5 is firmware-6.1.5-src.tar.
Further instructions are captured in the README file stored in the source code archive. Please proceed with the opensource component (re-)build by following these instructions.
Please note that all our patches to opensource components are included in the sources in the form of stand-alone patches so you can quickly identify the original code and the patches.
Because you have all the original code and also the patches, it is very easy to build a complete firmware image (note this FW image lacks all the proprietary components but it is still able to run the device to a certain point). However, the device checks firmware signatures and as the signing key is kept secret, the router will recognize that you are trying to upgrade to a non-signed firmware version and it will refuse the flashing.
But there are for sure ways how can you get virtually any opensource component replaced - if you ssh into the device as a root, you can write to any file, so replacing an opensource element with another one, upgrading some tool to a newer version or providing a different library version is quite easily achievable.
By saying you can replace any file you can also replace the Linux kernel. The important note is that if you replace the kernel with some non-functional kernel, the device may cease booting and there will be no easy way of fixing it.
All of these actions are done on your responsibility and any such action means that you are running custom firmware. Please read the following note on running the custom firmware prior to doing so.
Important note on running custom firmware
- It is hard to decide what action is small and causes no or small effect on the device and which is big and impacts the running OS a lot. Sometimes a small change can have a very significant impact on a system. Please consider that replacement of a small opensource utility with a newer version or a different utility may have an unforeseen impact - for example, such utility may be used by another part of the OS and because the new versions may change the meaning of the parameters, the effect on the system may be that a feature is rendered unusable, or even may cause malfunction of a router.
- Because Advantech CZ R&D is not the author of the change, it cannot be held responsible for any effect caused by running a custom firmware. Also, our device consists of not only hardware and software but also certifications from 3rd parties, providing guarantees for certain parameters of the device behavior to our users. As a result of the changes, the guarantees may be rendered invalid.
- As a result of the above, the producer of the original device (HW, SW, certifications) must protect itself against the potential effects of the changes. Note there is no bad intention captured in the following paragraphs but simply the fact that the product consists of multiple layers means, that by changing some of the layers (software equipment being one of the layers), the result is actually something different than was originally produced.
- When using purely custom-made firmware (without proprietary components), note that such firmware will miss all the features implemented by proprietary SW. Some of the device HW capabilities may not be fully supported by opensource. Because some of the original OS functionality is provided by proprietary code, you will lose some functionality.
- Because SW drives the HW, running custom firmware completely voids the device warranty.
- The device is no longer covered by certifications printed on the labels and the Declaration of Conformity is no longer valid. You are obliged to remove the stickers stating the conformity with all telecommunication certifications (by driving the HW components you can possibly override the limits of the HW so that you can break legal limits applicable to your country (if you hack internal HW limitations)).
- Also, note that by not following proper HW chip handling (e.g. using the wrong power-down sequence for the cellular module) you can significantly reduce the lifetime of the device and thus damage the HW.
- If you want to distribute the device to another user, you are also obliged to remove the Advantech Czech s.r.o. label as we are no longer the manufacturer of the whole device (device consists of both HW and SW) and no warranty applies. If you are interested in branding our products (possibly with your own OS), contact our business representatives.
- Such firmware is strictly unsupported by Advantech Czech s.r.o. You are completely on your own. If you manage to brick the device to an unbootable state (e.g. you break the boot loader or destroy data stored in MRAM), the device may get unusable or un-updatable to the official ICR-OS. If you send such a broken device for repairs, restoring the device to an operation state (with ICR-OS installed) will be subject to a support fee because the device is no longer in the warranty period.
- When you try to upload such firmware images to the device (ATM running official ICR-OS, you will get a warning because such an image is not digitally signed by the manufacturer. You may accept the risk (and void warranty) by proceeding with the operation. Note that digital signature applies only to v3 generation devices.
Tips for compilation
You can use make DEBUG=1 to cross-compile a Router App (User Module) with debug symbols for the GDB.
You can use make WARN=1 or make WARN=2 to cross-compile a Router App (User Module) with additional warning messages from the GCC.
You can use make ASAN=1 to cross-compile a Router App (User Module) with enabled Address Sanitizer.
You can use make UBSAN=1 to cross-compile a Router App (User Module) with an enabled Undefined Behavior Sanitizer.
You can use make SSP=1 to cross-compile a Router App (User Module) with enabled Stack Smashing Protector.
You can use make upload [ROUTER=<IP address>] [USERNAME=<username>] [PASSWORD=<password>] to upload Router App (User Module) directly into the router.
You can use make -j8 to speed up cross-compilation significantly on multicore systems.
You can install cache to speed up recompilation significantly.
You can set environment variable GCC_COLORS to enable the colorization of GCC output.