====== SDK ======
NetModule routers are shipping with a Software Development Kit (SDK) which offers a simple and fast way to implement customer-specific functions and applications. It consists of:
  - An SDK host which defines the runtime environment (a so-called sandbox), that is, controlling access to system resources (such as memory, storage and CPU) and, by doing so, catering for the right scalability.
  - An interpreter language called arena, a light-weight scripting language optimized for embedded systems, which uses a syntax similar to ANSI-C but adds support for exceptions, automatic memory management and runtime polymorphism on top of that.
  - A NetModule-specific Application Programming Interface (API), which ships with a comprehensive set of functions for accessing hardware interfaces (e.g. digital IO ports, GPS, external storage media, serial ports) but also for retrieving system status parameters, sending E-Mail or SMS messages or simply just to configure the router. 

Anyone, reasonably experienced in the C language, will find an environment that is easy to dig in. However, feel free to contact us via [[support@netmodule.com]] and we will happily support you in finding a programming solution to your specific problem.
===== The Language =====
The arena scripting language offers a broad range of POSIX functions (like printf or open) and provides, together with tailor-made API functions, a simple platform for implementing any sort of applications to interconnect your favourite device or service with the router.
Here comes a short example:
<code c example.are>
/* We are going to eavesdrop on the first serial port
* and turn on lights via a digital I/O output port ,
* otherwise we 'd have to send a short message .
*/
for ( attempts=0; attempts<3; attempts ++) {
  if ( nb_serial_read ("serial0") == "Knock Knock !") {
    nb_serial_write ("serial0", "Who 's there ?");
    if ( nb_serial_read ("serial0") == " Santa ") {
      printf (" Hurray !\n");
      nb_dio_set ("out1", 1);
    }
  }
}
nb_sms_send ("+123456789", "No presents this year :(")
</code>
A set of example scripts can be downloaded directly from the router, you can find a list of them in the appendix. The [[https://share.netmodule.com/public/system-software/4.8/4.8.0.102/NB_SDK_Arena_Manual_4.8.0.102.pdf|SDK language manual]] gives a detailed introduction of the language, including a description
of all available functions.

===== SDK API Functions =====
The current range of API functions can be used to implement the following features:
  - Send/Retrieve SMS
  - Send E-mail
  - Read/Write from/to serial device
  - Control digital input/output ports
  - Run TCP/UDP servers
  - Run IP/TCP/UDP clients
  - Access files of mounted media (e.g. an USB stick)
  - Retrieve status information from the system
  - Get or set configuration parameters
  - Perform config/software updates
  - Write to syslog
  - Transfer files over HTTP/FTP
  - Get system events / Reboot system
  - Control the LEDs
  - Get system events or reboot system
  - Scan available networks
  - Web Pages
  - Voice control functions
  - SNMP functions
  - CAN socket functions
  - MODBUS functons
  - Various network-related functions
  - OPC-UA functions (coming soon)
  - Encode functions (coming soon)
  - Other system-related functions
The [[https://share.netmodule.com/public/system-software/4.8/4.8.0.102/NB_SDK_API_Manual_4.8.0.102.pdf|SDK API manual]] provides an overview but also explains all functions in detail.

Please note that some functions require the corresponding services (e.g. E-Mail, SMS) to be properly configured prior to utilizing them in the SDK. Let us now pay some attention to the very powerful API function ''nb_status''. It can be used to query the router’s status values in the same manner as they can be shown with the CLI. It returns a structure of variables for a specific section (a list of available sections can be obtained by running ''cli status -h'').

By using the dump function you can figure out the content of the returned structure:
<code c sample2.are>
/* dump current location */
dump ( nb_status (" location "));
</code>
The script will then generate lines like maybe these:
<code c sample3.are>
struct(8): {
.LOCATION_STREET = string[11]: "Bahnhofquai"
.LOCATION_CITY = string[10]: "Zurich"
.LOCATION_COUNTRY_CODE = string[2]: "ch"
.LOCATION_COUNTRY = string[11]: "Switzerland"
.LOCATION_POSTCODE = string[4]: "8001"
.LOCATION_STATE = string[6]: "Zurich"
.LOCATION_LATITUDE = string[9]: "47.3778058"
.LOCATION_LONGITUDE = string[8]: "8.5412757"
}
</code>

In combination with the ''nb_config_set'' function, it is possible to start a re-configuration of any parts of the system upon status changes.
Here is an example how one might adopt those functions:
<code c sample4.are>
/* check current city and enable the second WAN link */
location = nb_status (" location ");
if ( location ) {
  city = struct_get ( location , " LOCATION_CITY ");
  if ( city == " Wonderland ") {
    for (led = 0; led < 5; led ++) {
      nb_led_set (led , LED_BLINK_FAST | LED_COLOR_RED );
    }
  } else {
    printf ("You 'll never walk alone in %s ...\ n", city );
    nb_config_set ("wanlink.1.mode=1");
  }
}
</code>

===== Running SDK ===== 
In the SDK, we are speaking of scripts and triggers which form jobs.
Any arena script can be uploaded to the router or imported by using dedicated user configuration packages. You may also edit the script directly at the Web Manager or select one of our [[sdk:sdk#Built-in Scripts|examples]]. You will further have a testing section on the router which
can be used to check your syntax or doing test runs.
Once uploaded, you will have to specify a **trigger**, that is, telling the router when the script is to be executed. This can be either time-based (e.g. each Monday) or triggered by one of the pre-defined system events (e.g. wan-up).
With both, a script and a trigger, you can finally set up an SDK ** job** now. The test event usually serves as a good facility to check whether your job is doing well. The admin section also offers facilities to troubleshoot any issues and control running jobs.
The SDK host (sdkhost) corresponds to the daemon managing the scripts and their operations and thus avoiding any harm to the system. In terms of resources, it will limit CPU and memory for running scripts and also provide a pre-defined portion of the available flash storage. You may, however, extend it by external USB storage or (depending on your model) SD cards. Files written to /tmp will be hold in memory and will be cleared upon a restart of the script. As your scripts operate in the sandbox, you will have no access to tools on the system (such as ''ifconfig'').

===== Simple How-To & Testing =====
  * [[sdk:Testing the SMS send script]]


===== Useful SDK Examples =====

==== Web Manager ====  
  * [[sdk:customized-web-gui-extension-display-and-change-custom-config-paramters|Custom Configuration Parameters]]
  * [[sdk:customized-web-gui-extension-display-and-change-custom-config-paramters|Web GUI extension]]
  * [[sdk:custom-wegpage-for-digital-output-pulse|Webpage Extention to send a Pulse on the Digital Output]]

==== Configurations ====
  * [[sdk:set-default-route-based-on-current-ssid|Set fake default route dynamically based on SSID]]
  * [[sdk:softwareupdate-on-change| Start softwareupdate if newer version is available]]
  * [[sdk:remote-configdownload | Request a unique remote config-file from a fileserver and delete it afterwards]]
==== Status Parameters ====
  * [[sdk::connection-statistics|Connection Statistics]]
  * [[sdk:status-values-via-snmp|Get status values via SNMP]]
  * [[sdk:status-values-via-snmp#extended-example|Monitor and reset data usage on mobile network]]
  * [[sdk::status2udp|Sends status values to a remote UDP server]]
  
==== Supervision ====
  * [[sdk::vpn-supervision|Supervising a VPN Tunnel]]
  * [[sdk:monitor-system-load| Monitor the system load and put a warning in the log file if critical]]
  * [[sdk:alarm-via-voice| Create a Phonecall Alarm]]
  * [[sdk:log-to-syslog| Log Status Values to Syslog]]
  * [[sdk:wwan_switcher|Change WWAN Hotlink according to the Service Type]]
==== GPS ====
  * [[sdk:gps-udp-broadcast|Broadcast selected GPS NMEA data to different UDP ports]]
  * [[sdk:gps-udp-client-GNSStoGPS|Send GNSS data to a remote UDP port in $GP instead of $GN format ]]

==== Serial ====
  * [[sdk:serial-point-to-multipoint|Serial Point to Multipoint]]
  * [[sdk::gps2serial|Write the GNSS NMEA Frames to the Serial Interface]]
  * [[sdk::gps2serial-gnsstogps|Write the GNSS NMEA Frames to the Serial Interface converted to GPS]]
  * [[sdk::serialDatalogger|Read data from the serial port and write it to files in the flash]]
  * [[sdk::hex2serial|Write non ASCII String to the Serial Port]]
==== HTTP ====
  * [[sdk::ftp2sms|Forward File Content of Files on FTP Server via SMS]]
  * [[sdk::httpGET| Webservices using HTTP GET]]
  * [[sdk::download-to-usb| Download a file from a HTTP Server and store it to a USB flash drive]]
==== Modbus ====
  * [[sdk::dio2modbusTCP|Access to the digital I/Os via Modbus TCP]]
  * [[sdk::ReadInputRegister-ModbusTCP-TempAlam|Read out a Modbus TCP Temperatur Sensor and send an alarm Email]]
  * [[sdk::ReadModbus-Janitza-UMG511|Read out a Janitza UMG511 via Modbus TCP]]
==== MQTT ====
  * [[sdk::mqtt_simple_status|Send Router Status Informations to an MQTT Broker]]
  * [[sdk::mqtt_advanced_status|Send Router Status Informations to an MQTT Broker - Advanced Version]]
  * [[sdk::mqtt_dio| Publish changes of the Digitial In or Out Interfaces via MQTT]]
==== Web Services ====
  * [[sdk::webservices_get|HTTP GET pass URL parameters/query strings]]
  * [[sdk::webservices_post|HTTP POST pass URL parameters/query strings]]
  * [[sdk::webservices_send_postion|send actual GNSS location via URL]]
==== Wifi / WLAN ====
  * [[sdk::wifimodechanger|Change Wifi Mode based on SSID]]
  * [[sdk::wifiprobingclients|Show probing WiFi clients]]
==== Various ====
  * [[sdk:telnet-run-a-command-using-telnet|Run a command using Telnet]]
  * [[sdk::tcp2sms| Sending SMS via TCP]]
  * [[internal:opcuaexample| Publish OPC-UA datas to the Web as JSON-Object also monitoring values]]
   






===== Helpful Functions =====    
    * [[sdk:ibis2ascii|Convert IBIS Telegrams to valid ASCII Strings (Umlaute)]]
    * [[sdk:castInt2float|Cast two Modbus Register on to one float variable]]
    * [[sdk:block-check-calculator|Calculate block check character]]


===== Built-in Scripts =====
^Script^Description ^
|[[sdk:scripts:best-operator|best-operator.txt]]| This script will scan for operators on startup and choose the one with the best signal|
|[[sdk:scripts:candump|candump.txt]]| This script can be used to receive CAN messages|
|[[sdk:scripts:config-summary|config-summary.txt]]| This script shows a summary of the currently running configuration.|
|[[sdk:scripts:dio-monitor|dio-monitor.txt]]| This script monitors the DIO ports and sends a SMS to the specified phone number.|
|[[sdk:scripts:dio-server|dio-server.txt]]| This script implements a TCP server which can be used to control the DIO ports.|
|[[sdk:scripts:dio|dio.txt]]| This script can be used to set a digital output port.|
|[[sdk:scripts:dynamic-operator|dynamic-operator.txt]]| This script will scan Mobile2 and dial the appropriate SIM on Mobile1|
|[[sdk:scripts:email-to-sms|email-to-sms.txt]]| This script implements a lightweight SMTP server which is able to receive mail and forward them as SMS to a phone number.|
|[[sdk:scripts:etherwake|etherwake.txt]]| This script can be used to wake up a sleeping host (WakeOnLan)|
|[[sdk:scripts:gps-monitor|gps-monitor.txt]]| A script for activating WLAN as soon as GPS position (lat,lon) is within a specified range.|
|[[sdk:scripts:gps-udp-client-compat|gps-udp-client-compat.txt]]| This script sends the local GPS NMEA stream (incl. serial/checksum) to a remote UDP server.|
|[[sdk:scripts:gps-udp-client|gps-udp-client.txt]]| This script sends the local GPS NMEA stream to a remote UDP server.|
|[[sdk:scripts:gps2serial-gnsstogps|gps2serial-gnsstogps.txt]]| This script sends the local GPS NMEA stream to the internal serial interface. t checks for the correct CR/LF end of line characters and convert messages $GN to $GP.|
|[[sdk:scripts:gps-upd-client-compat|gps-upd-client-compat.txt]]| This script sends the local GPS NMEA stream to a remote UDP server (incl. device identity).|
|[[sdk:scripts:led|led.txt]]| This script can be used to set a LED|
|[[sdk:scripts:modbus-rtu-master|modbus-rtu-master.txt]]| This script can be used to read messages from the serial port.|
|[[sdk:scripts:modbus-rtu-slave|modbus-rtu-slave.txt]]| This script implements a modbus slave server|
|[[sdk:scripts:modbus-tcp-rtu-gateway|modbus-tcp-rtu-gateway.txt]]| This script can be used to read messages from the serial port.|
|[[sdk:scripts:mount-media|mount-media.txt]]| This script can be used to mount an USB storage stick.|
|[[sdk:scripts:opcua-browse|opcua-browse.txt]]| This script can be used to browse the Addressspace of an OPC-UA-Server. (coming soon)|
|[[sdk:scripts:opcua-read|opcua-read.txt]]| This script can be used to read the value from a Node at a OPC-UA-Server. (coming soon)|
|[[sdk:scripts:opcua-search|opcua-search.txt]]| This script can be used to search for some Nodes at a OPC-UA-Server. (coming soon)|
|[[sdk:scripts:opcua-write|opcua-write.txt]]| This script can be used to write a new value to a Node at a OPC-UA-Server. (coming soon)|
|[[sdk:scripts:ping-supervision|ping-supervision.txt]]| This script will supervise a specified host.|
|[[sdk:scripts:read-config|read-config.txt]]| This script can be used to read a configuration parameter.|
|[[sdk:scripts:remote-mail|remote-mail.txt]]| This script reads and sends mails from a remote IMAP/POP3/SMTP server|
|[[sdk:scripts:scan-mobile|scan-mobile.txt]]| This script can be used to switch the Mobile LAI according to available networks|
|[[sdk:scripts:scan-wlan|scan-wlan.txt]]| This script can be used to switch the WLAN client network according to availability|
|[[sdk:scripts:send-mail|send-mail.txt]]| This script will send an E-Mail to the specified address.|
|[[sdk:scripts:send-sms|send-sms.txt]]| This script will send an SMS to the specified phone number.|
|[[sdk:scripts:serial-read|serial-read.txt]]| This script can be used to read messages from the serial port.|
|[[sdk:scripts:serial-readwrite|serial-readwrite.txt]]| This script will write to and read from the serial port.|
|[[sdk:scripts:serial-tcp-broadcast|serial-tcp-broadcast.txt]]| This script reads messages coming from the serial port and forwards them via TCP to remote hosts (and vice versa).|
|[[sdk:scripts:serial-tcsetattr|serial-tcsetattr.txt]]| This script can be used to set/get the attributes of the serial port.|
|[[sdk:scripts:serial-udp-server|serial-udp-server.txt]]| This script reads messages coming from the serial port and forwards them via UDP to a remote host (and vice versa).|
|[[sdk:scripts:serial-write|serial-write.txt]]| This script can be used to write a message to the serial port.|
|[[sdk:scripts:set-ipsec-route|set-ipsec-route.txt]]| set route to IPSEC server depending on active WWAN / WLAN network|
|[[sdk:scripts:sms-control|sms-control.txt]]| This script will execute commands received by SMS.|
|[[sdk:scripts:sms-delete-inbox|sms-delete-inbox.txt]]| This script can be used to flush the SMS inbox.|
|[[sdk:scripts:sms-read-inbox|sms-read-inbox.txt]]| This script can be used to read the SMS inbox.|
|[[sdk:scripts:sms-to-email|sms-to-email.txt]]| This script will forward incoming SMS messages to a given E-mail address.|
|[[sdk:scripts:sms-to-serial|sms-to-serial.txt]]| This script can be used to write a received SMS to the serial port.|
|[[sdk:scripts:snmp-agent|snmp-agent.txt]]| This script extends MIB entries of the SNMP agent|
|[[sdk:scripts:snmp-cmd|snmp-cmd.txt]]| This script issues SNMP set/get commands|
|[[sdk:scripts:snmp-trap|snmp-trap.txt]]| This script can be used to send SNMP traps|
|[[sdk:scripts:status|status.txt]]| This script can be used to display all status variables|
|[[sdk:scripts:syslog|syslog.txt]]| Throw a simple syslog message.|
|[[sdk:scripts:tcpclient|tcpclient.txt]]| This script sends a message to a TCP server.|
|[[sdk:scripts:tcpserver|tcpserver.txt]]| This script implements a TCP server which is able to receive messages.|
|[[sdk:scripts:techsupport|techsupport.txt]]| This transfers a techsupport to a remote FTP server|
|[[sdk:scripts:transfer-file|transfer-file.txt]]| This scripts archives a remote file|
|[[sdk:scripts:transfer|transfer.txt]]| This scripts stores the latest GNSS positions in a remote FTP file|
|[[sdk:scripts:udp-msg-server|udp-msg-server.txt]]| This script will run an UDP server which is able to receive messages and forward them as SMS/E-Mail.|
|[[sdk:scripts:udpclient|udpclient.txt]]| This script sends a message to a remote UDP server.|
|[[sdk:scripts:udpserver|udpserver.txt]]| This script implements an UDP server which is able to receive messages.|
|[[sdk:scripts:update-config|update-config.txt]]| This script can be used to perform a configuration update|
|[[sdk:scripts:voice-dispatcher-audio|voice-dispatcher-audio.txt]]| This script implements an audio voice dispatcher|
|[[sdk:scripts:webpage|webpage.txt]]| This script will generate a page which can be viewed in the Web Manager|
|[[sdk:scripts:write-config|write-config.txt]]| This script can be used to set a configuration parameter.|


===== Access the Filesystem =====

You can acces the SDK Filesystem externaly via SCP:

With Windows you can use the opensource software [[https://winscp.net/eng/download.php|WinSCP]]

Connect with the Protocoal SPC, User "root" and your admin password:

{{ :sdk:screenshot_-_08222017_-_11_04_08_am.png?nolink | WinSCP Configuration}}

Please then go to the folder 

<code>
/home/sdk/sandbox/
</code>

Where you find the Filesystem which is usable from the SDK


{{ :sdk:screenshot_-_08222017_-_11_03_05_am.png?nolink | WinSCP Remote SDK Folder}}