Net Comm Wireless Software Development Kit Feature Spotlight

Net. Comm Wireless Software Development Kit Feature Spotlight

The Software Development Kit Net. Comm Wireless provide a software development kit (SDK) to allow third parties to develop custom software applications for our routers. As our routers operate a linux-based kernel, the SDK should be unpacked and installed on a Linux machine. To get you started, the SDK includes two examples – a kernel driver and a userspace application.

The Software Development Kit Users can create their own applications to extend the functionality of the device. Applications can be distributed as ‘packages’ in IPK format and may be installed either locally on a Net. Comm Wireless router via the Web-UI upload page, or remotely via SMS/TR 069. Packages that you create can easily be inserted into regular firmware upgrade images for easy mass-deployment.

System overview The Net. Comm Wireless platform is designed for ease of development. As such, it has relatively large reserves of FLASH, SDRAM and computing power. It is also quite forgiving of developer errors and can recover from most failures. RECOVERY VS. MAIN The router has two independent systems, each with its own kernel and file system. These are referred to as “Main” and “Recovery”. You can always use one system to restore the other. BOOT SEQUENCE The bootloader attempts to load the main system by default. If that fails, it loads the recovery system. If that fails too, the bootloader attempts to fetch a recovery system kernel and rootfs from an external TFTP server. On success, those images are automatically flashed. You can force the router to boot into recovery mode by using the reset button.

The Runtime Database (RDB) The Runtime Database is an inter-process communication and storage system using variables. Most applications on the router use the RDB either directly or indirectly. This provides comprehensive device status and configuration via a simple key value pair system Processes can create, read or write variables. They can also be notified if any of the variables are changed. Access can be controlled with a user-based access control scheme. Database variables are identified by name strings, usually in field notation. Names tend to be self-explanatory and can be used to group data into records e. g. “link. profile. 1. auth_type” and “link. profile. 1. status” are variables related to link profile 1. Database variables can contain arbitrary binary data, but most contain human readable strings. Database variables can also contain flags that describe properties, for example, a variable can be “persistent”, which is a variable that survives a reboot.

The Runtime database Variables are subject to access control permissions, similar to Unix files. There are three permission groups (owner, group & others) and four flags in each group (read, write, erase, perm). By manipulating the permissions, a task can, for instance, create a variable everyone can write to, but only the owner may read (e. g. password check). Database variables have an additional ‘flags’ field which denotes special variable properties and behaviour: FLAG DESCRIPTION PERSIST Variables with this flag set will be automatically shadowed in the system settings file. That is, they get populated from the settings file at system start and after that, the settings file on disk will mirror the contents. CRYPT Variables with this flag set use reversible encryption on their data fields when exported to an external file. This must be used in conjunction with PERSIST, and is set for passwords, PIN numbers, etc. HASH Similar to crypt, but uses a one-way cryptographic hash. Rarely used - it can be used to store a password in a non-reversible way. Useful for checking credentials - same passwords result in the same hash. READ_ONCE Variable self destructs after one read. Used for temporary keys or other credentials. Avoids inadverted leaking of critical information.

The command line A command line tool is provided to manipulate the RDB, for use within scripts and on the system’s command line. This is a single binary file that may be called using one of the three names rdb_get, rdb_set or rdb_wait. rdb_get Used to fetch a list of variables or read a single variable. Here is an example of how to retrieve all variables with the “snmp” string: root: # rdb_get –L snmp service. snmp. enable 0 service. snmp. name. readwrite private service. snmp. name. readonly public

The command line How to retrieve signal strength (RSSI): root: ~# rdb_get wwan. 0. radio. information. signal_strength -80 d. Bm root: ~# How to retrieve the APN for a particular profile: root: ~# rdb_get link. profile. 1. apn telstra. extranet root: ~# How to retrieve WWAN IP Address for Profile 1: root: ~# rdb_get link. profile. 1. iplocal 123. 209. 5. 2 root: ~#

The command line rdb_set Used to set a variable. Here’s an example of creating a new variable: root: # rdb_set testvar test Read back the new variable: root: # rdb_get testvar test How to configure APN for Profile 2: root: ~# rdb_set link. profile. 2. apn testapn Confirming that the APN was configured to “testapn” root: ~# rdb_get link. profile. 2. apn testapn root: ~#

The command line rdb_wait Used to launch a background task waiting for the variable to be updated. root: # rdb_wait testvar && echo "Got '`rdb_get testvar`'" & Now you can set the variable: root: # rdb_set testvar 'new value' root: # Got 'new value' [2] + Done rdb_wait testvar && echo "Got '"$(. . . )"'"

Some final words on SMS Forwarding SMS Diagnostics and SMS Forwarding may be used at the same time When SMS forwarding is enabled, all messages are passed to the downstream device, including SMS Diagnostics messages. The downstream device should be capable of filtering out the irrelevant messages. SMS messages may be forwarded a TCP port and a UDP port simultaneously. An optional feature for use in Op. Cos rather than GDSP use is that SMS messages may also be forwarded to another mobile number in addition to via TCP and/or UDP.

Launching your application There a few ways of launching your new application: launch it at system boot by inserting a line into /etc/inittab add a system startup script create an RDB template RDB TEMPLATES Templates are scripts which are triggered based on system events – changes to RDB variables. Templates are stored in /etc/cdcs/conf/mgr_templates/. They are mostly scripts with a grammar extension to allow them to specify a list of RDB variables to which they are sensitive. All templates run once at boot time and then every time any of the sensitive variables are written, even if the value remains the same.

Templates Here is an example of a template which sends an SMS when the signal strength falls below -100 d. Bm and sends an SMS when the signal strength recovers: #!/bin/sh SIGNAL="? <wwan. 0. radio. information. signal_strength>; " log() { logger -t "signal_sms. template" -- "$@" } d. Bm="-100" recv="0412345678" SIGNAL=$(echo "$SIGNAL" | sed 's/d. Bm//g') # get previous signal strength PREV_SIGNAL=$(rdb_get "wwan. 0. radio. information. signal_strength. prev") if [ -z "$PREV_SIGNAL" ]; then PREV_SIGNAL=0 fi # if raising edge is detected if [ $PREV_SIGNAL -ge $d. Bm -a $SIGNAL -lt $d. Bm ]; then log "[sendsms] signal drops to $SIGNAL / below $d. Bm" sendsms -- "$recv" "signal drops to $SIGNAL / below $d. Bm" DIAG # if failling edge is detected elif [ $PREV_SIGNAL -lt $d. Bm -a $SIGNAL -ge $d. Bm ]; then log "[sendsms] signal recovers to $SIGNAL / above $d. Bm" sendsms -- "$recv" "signal recovers to $SIGNAL / above $d. Bm" DIAG fi # store current to previous rdb_set -- "wwan. 0. radio. information. signal_strength. prev" "$SIGNAL”

Templates Below is a very basic template which runs every time the first connection is made and the WAN IP address is available: #!/bin/sh WANIP="? <link. profile. 1. iplocal>; " echo ''$WANIP'' >/tmp/wanip. txt ftpput some-remote-server. com 3 g_ip. txt /tmp/wanip. txt This template places any new 3 G IP address into a file and uploads that file via FTP to a remote machine - a very primitive form of creating a dynamic DNS system.

LEDs The LEDs are available via the standard sysfs interface. When using them for custom applications, care must be taken to avoid conflicts with existing functionality. In general, normal operation of the LEDs tends to operate via triggers (see below), which can be switched off. There a few cases where LED state is also controlled or modified within RDB templates, e. g. RSSI and DCD LEDs. For most simple applications, it is sufficient to update the LED state about once per second, thus overriding the templates. Beyond that, it may be necessary to disable the relevant templates.

User interface (Appweb) The Web-based user interface is currently built around the Appweb server. This server supports server side scripting and is linked with the RDB system, such that server side (ESP) scripts have access to RDB variables. Web interface related files are located in the /www directory, which acts as the web server root. CUSTOM MENUS The Net. Comm Wireless platform has a mechanism for easily adding menu items, without having to edit existing files. Part of the menu bar is generated dynamically from the contents of the /www/usermenu directory. This directory contains simple text files, whose name is used as the menu entry and whose content is the link to invoke. For example, this command line sequence adds a link that returns the name of the current 3 G provider: root: # cd /www/usermenu root: /www/usermenu# echo "cgi-bin/rdb. cgi? wwan. 0. service_provider_name" > "Provider" /etc/init. d/rc. d/usermenu

Further information More information: This presentation is a brief introduction to the possibilities available with the Software Development Kit. For more information on the SDK please see the SDK documentation available on the Net. Comm Wireless website.