Constraints

S1 Router Programming Considerations

S1 routers have specific characteristics affecting Router App development, primarily related to its security model and read-only filesystem.

Extending the Read-Only Root Filesystem

On S1 Routers, the root filesystem is mounted read-only and cannot be directly modified. However, functionality can be extended using Router Apps, which are installed as read-only SquashFS overlays mounted over specific directories like /opt and potentially /usr.

Other writable partitions, such as the persistent /var and volatile /run and /tmp directories, are mounted with the "noexec" option. This prevents the execution of binaries directly from these locations. Therefore, executable files (binaries, scripts intended for direct execution) must be packaged within a Router App and placed in appropriate locations within the overlay (e.g., /opt/<RAname>/bin).

Examples example8 and example9 within the ModulesSDK demonstrate how to structure a Router App to add files to the /usr directory via the overlay mechanism. To build such an example (e.g., for the v2i-S1 platform):

cd modules/example8
make PLATFORM=v2i-S1

This build process generates a *.raw file. This .raw file is the Router App package for S1 platforms and can be installed using the standard Router App installation procedure in the web interface.

Adding JavaScript and CSS to the S1 Web Administration Interface

The S1 router's web server enforces a strict Content-Security-Policy (CSP). Inline JavaScript code and CSS styles are generally blocked unless specific mechanisms are used. To include custom JavaScript or CSS within web pages generated by your Router App (e.g., CGI scripts) on S1 routers, they must be embedded within <script> or <style> tags that include a dynamically generated nonce (number used once) attribute.

The ModulesSDK (version 2.2.1 and later) provides helper functions, um_html_js and um_html_css, designed to handle this correctly for C-based CGI. These functions automatically incorporate the required nonce when embedding scripts or styles. Example usage within a C-based CGI script using the SDK:

// Example: Set focus on the username field after the page loads
um_html_js("document.f.username.focus();\n");

// Example: Add a simple CSS rule
um_html_css(".my-class { color: blue; }\n");

For Python CGI scripts, the um Python module provides the equivalent functions um.html_js() and um.html_css() (and um.html_js_external() for external script files).

Changing System Configuration Programmatically on S1 Routers

Configuration files on S1 routers include an integrity check (checksum) to prevent unauthorized modifications. To change system configuration settings from within a Router App script, you cannot simply edit the configuration files directly. Instead, follow this procedure:

Create a partial configuration backup file (e.g., /tmp/backup.cfg) containing only the settings you wish to change, formatted correctly (e.g., ETH_IPADDR=192.168.1.100).
Calculate the SHA512 hash of this partial backup file and append it to the file itself in the format INTEGRITY=CFG_HASH=<hash_value>.
Use the restore command (with appropriate privileges, usually via sudo if available/required in the script context) to apply the changes from this integrity-checked partial backup file.

Example script snippet:

#!/bin/sh
# Create a temporary partial config file
cat << EOF > /tmp/backup.cfg
ETH_IPADDR=192.168.1.100
ETH_NETMASK=255.255.255.0
EOF

# Calculate hash and append integrity line
HASH_VAL=$(openssl sha512 /tmp/backup.cfg | awk '{print $2}')
echo "INTEGRITY=CFG_HASH=$HASH_VAL" >> /tmp/backup.cfg

# Apply the configuration change (requires appropriate permissions)
# The use of 'sudo' depends on the execution context of the script.
# If the script itself runs as root (e.g. some init scripts), sudo might not be needed.
# Otherwise, ensure the user/context has sudo rights for 'restore'.
sudo restore /tmp/backup.cfg

# Clean up temporary file
rm /tmp/backup.cfg

Tips

Ensure the user/context running this script has permissions to execute sudo restore. The exact mechanism may vary depending on how your script is invoked by the system.

Hardware Constraints

Non-volatile Memory

Routers are embedded systems with limited resources. Efficient use of storage, RAM, and CPU is crucial.

Router Apps are installed in the /opt directory. Additionally, persistent data that needs to survive reboots but is generated or modified at runtime can often be stored in the /var/data directory. The type and size of non-volatile memory available for these directories vary depending on the router platform, as shown in the tables below.

Characteristics of the `/var/data` Directory Partition

Parameter	v1	v1i	v2i	v2i with eMMC	v3	v3 with eMMC	v4	v4i
Memory type	NAND	NAND or eMMC¹	NOR	eMMC	MRAM	eMMC	eMMC	eMMC
File system	—	—	JFFS2	ext4	JFFS2	ext4	ext4	ext4
Part. size	~26 MB	~11–491 MB¹	2 MiB	512 MiB	128 KiB	512 MiB	512 MiB	474 MiB

¹ ICR-1700 (v1i) ships in multiple hardware variants: a dual-core variant with 256 MB NAND flash (~11 MB for persistent data) and a quad-core variant with 4 GB eMMC (~491 MB for persistent data). Check your specific router's hardware manual for the exact figure.

Characteristics of the `/opt` Directory Partition

Parameter	v1	v1i	v2i	v2i with eMMC	v3	v3 with eMMC	v4	v4i
Memory type	NAND	NAND or eMMC¹	NOR	eMMC	NOR	eMMC	eMMC	eMMC
File system	—	—	JFFS2	ext4	JFFS2	ext4	ext4	ext4
Part. size	~65 MB	~20–1000 MB¹	12 MiB	814 MiB	128 MiB	838 MiB	838 MiB	2.16 GiB

¹ ICR-1700 (v1i) ships in multiple hardware variants: a dual-core variant with 256 MB NAND flash (~20 MB for Router Apps) and a quad-core variant with 4 GB eMMC (~1 GB for Router Apps). Check your specific router's hardware manual for the exact figure.

Caution

On platforms where the /var/data partition uses MRAM and is 128 KiB in size (e.g., standard v3 routers), it is strongly recommended that a Router App uses no more than 64 KiB of this space. The remaining space is required by the router's operating system for its own persistent data storage.

Notes:

The JFFS2 filesystem used on some NOR flash partitions supports compression. This means you might be able to store more data than the raw partition size suggests if the data compresses well.
It is standard practice for a Router App needing persistent runtime data storage to create its own subdirectory within /var/data, e.g., /var/data/<RAname>. This should typically be done in the install or init start script.
The system typically automatically deletes the /var/data/<RAname> subdirectory (if it exists) when the corresponding Router App is uninstalled.
Cleanup of any other files or subdirectories created by the Router App outside of /opt/<RAname> or /var/data/<RAname> is the responsibility of the Router App author (usually handled in the uninstall script).

RAM Utilization

Refer to the table below for the amount of RAM available on different router platforms. Router Apps can use standard dynamic memory allocation functions (e.g., malloc in C/C++, equivalent mechanisms in Python). Exercise caution regarding memory consumption; ensure your Router App does not deplete system memory, which could negatively impact router stability and performance.

RAM Memory Parameters

Parameter	v1 routers	v1i routers	v2i routers	v3 routers	v4 routers	v4i routers
RAM size	256 MB	512–1024 MB¹	128 MB	512 MB	1024 MB	1024 MB

¹ ICR-1700 (v1i) ships in multiple hardware variants: a dual-core variant with 512 MB RAM and a quad-core variant with 1024 MB RAM. Check your specific router's hardware manual for the exact figure.

CPU Performance Considerations

There are CPU parameters for different router platforms listed in the table below. When developing applications, consider these CPU constraints:

Choose the development language appropriate for the task. C/C++ generally offers better performance for CPU-intensive operations than interpreted languages like Python or shell scripts.
Avoid busy-waiting or tight loops that can consume excessive CPU.
Offload complex computations to external systems if feasible and appropriate for your application.
Profile your application if performance issues arise.

CPU Architecture

Parameter	v1 routers	v1i routers	v2i routers	v3 routers	v4 routers	v4i routers
CPU	—	—	SAM9X60	AM3352	—	—
Architecture	arm v7	arm v8	arm 5TEJ	arm v7	arm v8	arm v8
Core	Cortex-A7	Cortex-A55¹	ARM926EJ-S	Cortex-A8	Cortex-A72	Cortex-A53
CPU power	1.9 DMIPS/MHz @ 1200 MHz	1.9 DMIPS/MHz @ 1.35–2.2 GHz¹	1.1 DMIPS/MHz @ 600 MHz	2 DMIPS/MHz @ 1000 MHz	4.72 DMIPS/MHz @ 1200 MHz	2.3 DMIPS/MHz @ 1600 MHz

¹ ICR-1700 (v1i) ships in multiple hardware variants: a dual-core Cortex-A55 variant at 1.35 GHz and a quad-core Cortex-A55 variant at 2.2 GHz. Check your specific router's hardware manual for the exact figure.

Understanding Cross-Compilation and Compiler Flags

Cross-compilation is the process of compiling code on one system (the development host, e.g., x86 Linux) to run on a different system (the target router, e.g., ARM). This requires a toolchain (compiler, linker, libraries) built for the target architecture.

If you choose to use a different cross-compiler than the ones officially provided (see Cross-Compiler Toolchains), or if you need to fine-tune build parameters, ensure you use appropriate compiler flags for the target platform to generate compatible binaries. Based on the router platform, use the following flags:

v2i routers (ARMv5TEJ):

-march=armv5te -mtune=arm926ej-s  -mfloat-abi=soft

v3 routers (ARMv7-A / Cortex-A8):

-march=armv7-a -mtune=cortex-a8 -mfpu=vfpv3 -mfloat-abi=softfp

v4 routers (ARMv8-A / Cortex-A72):

-march=armv8-a+crc+crypto -mtune=cortex-a72

v4i routers (ARMv8-A / Cortex-A53):

-march=armv8-a+crc+crypto -mtune=cortex-a53

v1 routers use the same toolchain and compiler flags as v3 routers, and v1i routers use the same toolchain and compiler flags as v4i routers — the ModulesSDK build system selects the matching toolchain automatically for PLATFORM=v1 or PLATFORM=v1i.