Netcomm

Overview

The following sections demonstrate how to use a NetComm router with Cumulocity. It describes how to

The following sections assume that the router has the NetComm agent package installed. The agent is compatible with the NTC-6200 and NTC-140W. For more information on a particular feature of the router, please consult the respective manual found in the "Downloads" section of the router's home page.

Configuring the router

The support for Cumulocity can be configured through the router's web user interface. To do so, login to the user interface as described in the router's manual. Navigate to the "System" tab and click on the "Internet of Things" menu item.

Cumulocity configuration

Verify that the toggle switch "Cumulocity agent" is set to "ON" and the URL shown in "Server" points to the Cumulocity instance that you want to connect. For example, use

Optionally, you can activate data collecting for the following functionalities:

  • GPIO analog measurements: Send the voltages of the analog inputs [seconds].
  • GPS position interval: Update the current GPS position [seconds].
  • GPS position event: Send a location trace of the GPS position [seconds].
  • System resources measurements: Get information about CPU usage, memory usage and network traffic [seconds].

All these options are disabled by default (the interval is set to 0).

The web interface also shows the status of the connection to Cumulocity:

(For version 2.x)

  • Off: The software is disabled.
  • Initializing: The software is initializing.
  • Registering: The device waits for being registered to Cumulocity (see next section).
  • Starting: The software starts all its components.
  • No credentials: The device did not get credentials for accessing Cumulocity, the credentials were deactivated, or the credentials were wrong.
  • Started: The software is started.
  • Connecting: The software is connecting to Cumulocity.
  • Connected: The software is connected to Cumulocity.
  • Disconnected: The software is not connected to Cumulocity.
  • Reconnecting: The software is retrying the connection.
  • Stopping: The software is terminating.

(For version 3.x onwards)

  • Checking network connection: waiting for mobile network connection at boot.
  • Bootstrapping: load credentials or request credentials from Cumulocity.
  • Integrating: Connecting to Cumulocity.
  • Loading plugins: loading Lua plugins.
  • Connected: The agent is successfully connected to Cumulocity.
  • No server URL: no or invalid server URL.
  • Bootstrap failed: Can not get credentials from Cumulocity.
  • Integration failed: can not connect to Cumulocity.
  • Create threads failed: not able to start reporter or device push.

Connecting the router

To register your NetComm router to Cumulocity, you need the router's serial number as Device ID. The registration process is described in section "Connecting devices" in the User Guide. The serial number is printed on the back side of the router as shown below. Alternately, it is also available in the router's web user interface. Navigate to "System", "Internet of Things" and view the "Device ID" field.

Users of version 2.x or upgrading from 2.x to 3.x should use the router's MAC address. Please make sure to use only lowercase letters and numbers when entering the MAC address. Do not use colons to separate the MAC address. For example, the MAC address from the picture would be entered as

006064dda4ae

MAC address

After clicking the "accept" button, navigate to "All devices", the router should appear here after registration. The default name of a router is "<model> (S/N <serial number>)", where <model> is the device model name. For example, the above router would appear as "NTC-6200-02 (S/N 165711141901036)". Click on the router to view the detailed information and to access the functionality described in the remaining sections of this document. In order to distinguish a registered router from other devices in the listing, you can change the router's name on the "Info" tab, which also displays basic information such as serial number of the router and SIM card data. After changing the name, remember to click "save changes" button at the bottom of the "Info" page.

Device details

Configuring network parameters

You can view and configure the essential mobile network ("WAN") and local area network ("LAN") parameters in the "Network" tab as shown in the screenshot below.

The mobile network ("WAN") parameters shown in the user interface correspond to the first profile stored in the router. These parameters can be remotely configured directly or via SMS.

For SMS configuring, the router needs to be configured to accept SMS commands. Consult the router's manual on the relevant parameters for SMS configuration, or use the router's web user interface. You also need to have an SMS gateway configured with your account. Contact support for setting up an SMS gateway. For more information on Device Shell, consult the user's guide.

Note configuring WAN parameters via both IP and SMS mode requires Cumulocity 7.26. When you configure a wrong APN setting, the device will lose mobile network connection and can only be managed by limited SMS functionality.

WAN parameters

LAN and DHCP parameters can be directly configured from Cumulocity as well.

LAN parameters

Managing software and firmware

The installed software and firmware on the router can be remotely managed using the standard software and firmware management feature from Cumulocity, as described in the Device management user's guide.

Software packages need to be in ipkg format and follow the naming convention "<package>_<version>_<arch>.ipk". Version numbers including letters are not supported. All package management methods (install, upgrade, downgrade, removal) are supported through the router's package manager. If software packages have dependencies, please make sure to install these first.

The package "smartrest-agent_<version>_arm.ipk" represents the NetComm agent. It is prohibited to remove this package from Cumulocity.

When upgrading from versions older than 2.1.1, the device needs to be re-registered.

Firmware can be uploaded and installed on the router as well. To successfully upgrade the firmware, make sure that the target firmware includes the agent package. If the agent package is not included in the target firmware, the agent will not start after the installation. Firmware files need to follow Netcomm's naming convention ("<name>_<version>.cdi").

Software/firmware

Monitoring system resources

You can record statistics of the router's system resources usage for troubleshooting purposes. The following statistics are available:

  • CPU load in percent.
  • Used and total memory in MB.
  • Uplink and downlink traffic over all interfaces in KB/sec.

By default, collection of resource statistics is disabled. They can be enabled by setting a non-zero collecting interval in the "System resources measurements" entry of the router user interface or using Device Shell:

set service.cumulocity.system_resources.interval=<interval>

Collected data can be accessed in the "Measurements" tab or in a dashboard.

Using GPS

To locate or trace the router, connect a GPS antenna to the router and enable its GPS functionality. Then configure the frequency of data collection by setting the "GPS position interval" and/or the "GPS position event" to a non-zero value. "GPS position interval" defines how often the current location of the router is updated. "GPS position event" defines how often the current location is stored as location update event for tracing. Similarly, you can set these parameters from Device Shell:

set service.cumulocity.gps.update_interval=<update interval>
set service.cumulocity.gps.interval=<event interval>

After you applied the configuration changes, wait a moment for the first GPS data to arrive, then refresh the page. A "Location" and a "Tracking" tab should now appear. See the "Location" and "Tracking" sections in the user guide for more information.

Using GPIO

The following GPIO functionalities are supported:

  • Send the voltage of an analog input as measurements to Cumulocity.
  • Raise or clear alarms when a digital input turn 1 or 0, respectively.
  • Write to a digital output remotely from Cumulocity.

Consult the documentation of your router for more information about its specific IO settings. The available functionalities may vary between different device models. For example, the NTC 6200 model supports GPIO pins 1-3, while the NTC 140W model supports only GPIO pin 1.

Analog input

To regularly poll the input voltage of a GPIO pin and send it to Cumulocity, set "GPIO analog measurements" to a non-zero value. Alternatively, use Device Shell:

set service.cumulocity.gpio.interval=<interval>
set service.cumulocity.gpio.<port>.notify=measurement

<port> is the numbering of the GPIO pin. For the NTC-6200, <port> can be 1, 2 or 3, while for NTC-140W, <port> can only be 1. The Visualized result is then visible in "Measurements".

Digital input

You can raise alarms from digital inputs. These can be configured using the router user interface or through Device Shell. The format is

set service.cumulocity.gpio.<port>.notify=alarm
set service.cumulocity.gpio.<port>.debounce.interval=<SECONDS>
set service.cumulocity.gpio.<port>.alarm.text=<ALARM_TEXT>
set service.cumulocity.gpio.<port>.alarm.severity=<severity>

Possible values for the notify parameter are:

  • off: The pin is disabled for any notification.
  • alarm: An alarm is raised when the pin reading is "high".
  • measurement: Analog reading of voltage will be send as measurement.

The debounce interval reduces electrical noise from the GPIO inputs: The shorter the interval, the noisier the value but the faster the reaction to signal changes. The default debounce interval is 10 mins.

You can override the default alarm text by setting the "text" property. By default, this value is empty and "gpio<N> is active" is used as text, where <N> is the numbering of a GPIO pin.

Valid alarm severities are:

  • WARNING
  • MINOR
  • MAJOR [default]
  • CRITICAL

The inputs are checked every second for changes.

Digital output

Digital outputs can be controlled using the "Relay array" plugin, see below in the screenshot. The numbering of the GPIO pins are the same as listed on the router. For the NTC-6200 model, three GPIO pins can be set, while for the NTC-140W model, only the first pin has effect.

Relay Array

Configuration Management

You can retrieve, modify and save user configuration data. To do this, navigate to the "Configuration" tab of the router, click on the "Reload" button in the "CONFIGURATION" widget to request configuration data. It will take a few seconds to download. After the configuration data has arrived, you will see a list of parameters and their corresponding values. You can then make changes to the configuration and save them back to the device.

You can also request a configuration snapshot from the device and later apply the configuration snapshot to other devices.

Starting from agent version 3.1.1 and Cumulocity version 7.26 there is also RDB snapshot support, which is a super-set of the configurations. This is mainly for troubleshooting purpose.

RDB setup

Prior to Cumulocity 6.9, this widget was in the "Control" tab. Starting from Cumulocity 6.9, you can also take entire configuration snapshots including the non-textual parts of the device and send reference configuration snapshots back to the device.

Configuring devices to use SMS mode

To use SMS commands for devices, open the router's web interface and navigate to "Services", "SMS messaging", then "Diagnostics". Configure the device as follows:

  • Either disable "Only accept authenticated SMS messages", or add permitted senders to the white list. Usage of passwords is not supported.
  • Turn the other settings on.

Enable SMS mode

For more information please refer to "Control devices via SMS".

Device Shell

With Device Shell, you can read and write individual configuration parameters from the device, as well as execute diagnostic commands. For more information, please refer to the user guide. Consult the Netcomm documentation for valid parameters and diagnostic commands. The general format is:

  • "get <parameter>" to read a parameter from the device.
  • "set <parameter>=<value>" to write a parameter to the device.
  • "execute <command>" to execute a diagnostic command on the device.

Multiple get, set and execute commands can be sent using a semicolon as separator. Click the "Get Predefined" link to access frequently used parameters and commands.

Device Shell

Event notifications

The router reports certain system events as notifications, which can be forwarded to Cumulocity as alarms. The system events help, for example, in troubleshooting mobile network issues. For more information on the different types of events and how to forward them, please consult the Netcomm documentation (for example, Section "Event notification" in the user's guide). To forward an event as alarm, set up a UDP destination sending to Port 1331 on localhost (Section "Destination configuration").

Event notifications

Cloud Fieldbus

You can connect Modbus-TCP and Modbus-RTU slaves to the router via LAN and serial port, respectively, and manage them remotely in Cumulocity. To do so, you need to

For Modbus-TCP setup:

  • Establish LAN connectivity. Use the "Network" tab as described above and the corresponding configuration mechanism on the Modbus device to enable IP communication between the router and the your Modbus-TCP slaves.
  • Configure the Modbus-TCP port in the Cumulocity menu on NetComm device's web UI if you are using a different port than the default 502, see "Configuring the router".

For Modbus-RTU setup:

  • Connect the router and your Modbus-RTU slaves via a serial cable.
  • Configure serial port mode via device shell:

      set serial.iomode.default=<mode>
    

where <mode> can be rs232, rs422 or rs485. You may need to reboot the device after changing the mode.

The default serial port /dev/ttyAPP4 should work with no further configuration. In case it's empty or you need to configure a different port, it can be configured in the Cumulocity menu in devices' web UI, see "Configuring the router".

Some USB to serial adapters have echo mode enabled by default, this can render the Modbus communication stop working completely. If you have one of these adapters, consult the adapter's manufacturer about how to disable it.

Model NTC-140W doesn't support modbus RTU, so you will not see the corresponding functionality in the UI.

Model NTC-140W doesn't support modbus RTU, so you will not see the corresponding functionality in the UI.

Then:

  • Subscribe your account to the Cloud Fieldbus app by contacting support.
  • Configure Modbus communication as described in the Cloud Fieldbus user's guide.
  • Enable or disable write permission by setting the "Modbus read only" property in the Cumulocity menu on the device's web UI, see "Configuring the router". Set it to 0 means allow write permission, while 1 means disallow Modbus write permission.

Log viewer

You can download and view logs from the device. Log files can be quite big, you can set filtering criteria to get only what is interesting for you.

From right you can set date range (date from and date to), you can select log file. Next you can search the text, and only matching lines are retrieved from the device. You can also limit matched lines.

Received logs are visible in a list below. You can click on it to show log file content at the bottom of the page. Last requested log is opened automatically.

Log viewer

VNC remote access

If you have a device which supports VNC, Telnet or SHH remote access, it's now possible to manage your device via Cumulocity starting from Agent v4.2.0.

As shown in the screenshot, you can add your VNC, Telnet or SSH servers as an endpoint with appropriate IP and port in the Remote Access tab of a particular device in the Device Management application. If you click Connect, the display content of your remote server will be shown in a new browser window.

Info: The "vncproxy" package is required and must be installed.

VNC

MQTT

Starting from v4.0.0, agent added supported for MQTT protocol. In case you want to upgrade from previous 2.x or 3.x versions, no additional configurations are required for enabling MQTT. However, in case you need to manually configure MQTT enablement, run following command via "Device Shell":

set service.cumulocity.mqtt.enable = <0|1>

to either disable or enable MQTT communication. The configured server URL remains the same. For example, http://demos.cumulocity.com if you want to use plain MQTT, or https://demos.cumulocity.com if you want secure MQTT + TLS.

Server URL http://developer.cumulocity.com will not work with MQTT since it points one different instance which doesn't have MQTT enabled. You should use http://demos.cumulocity.com instead.

To configure the MQTT keepalive interval (default to 240 seconds):

set service.cumulocity.mqtt.keepalive = <seconds>

to change the keepalive interval.

Changing keepalive interval only has affect after the next reboot.

Netcomm Agent Developer's Guide

Index:

Configuration

Credentials

Credentials are stored in RDB in values:

  • service.cumulocity.connection.username – with tenant, for e.g. management/device_006064ce80bf
  • service.cumulocity.connection.password – mangled password

Password format is:

  • *1* – prefix
  • mangle process:
    • password, if is smaller that 16 character it's filled up to 16 bytes from string fN4\033q8!7n\n13Q$8f
    • xor'ed with string \x21\x63\x0e\x30\x2f\x1b\x9a\xc2\x34\x55\xe8\x7d\x32\xda\x30\xea\x59
    • base64
  • *– suffix

Event notifications

Cumulocity alarms are base on NetComm UDP events described in NetComm Wireless M2M Device Model (ver.1.3). The agent use definitions from file /usr/local/etc/udp_alarms.ini. There are:

  • general section [alarm]
  • per event sections [alarm.N], where N is event number (from M2M Device Model)

Alarm section contains severity value, default is MAJOR. You can overwrite it.

Each event section contains:

  • event number in section name
  • name – alarm name, defined in M2M Device Model, used also as notification type
  • severity – overwrites default severity, optional, default: non exists
  • type – Cumulocity notification type, overwrites names, optional, default: non exists

Text from UDP event is directly set as notification in Cumulocity.

Log viewer

Log viewer plug-in (lua__logs) uses definitions from file /usr/local/etc/logs.ini. There are list of supported logs in global value logs:

logs = logread, dmesg, sragent

This is names of logs declared in Cumulocity and list of sections with log details.

Each section contains:

  • file or execute – log source, when execute is used, log is got from standard output
  • pattern – line parse pattern in Lua RegEx syntax (tutorial)
  • fields – names of parsed fields in RegEx sub-patterns, if name is used more that one time sub-patterns are joined with space separator
  • timeFormat – time format used in this log:
    • strptime format,
    • $(uptime) – time offset form system start (useful for dmesg)

Example: [syslog] file = /var/log/syslog pattern = (%a+ +%d+ +%d+:%d+:%d+)%s+%S+%s+(%S+):%s(.)%s*$ fields = time, module, text timeFormat = %B %d %T

[logread]
execute = logread
pattern = (%a+ +%d+ +%d+:%d+:%d+)%s+%S+%s+(%S+)%s+(%S+):%s*(.*)%s*$
fields = time, level, module, text
timeFormat = %B %d %T

Netcomm Release Notes

Release notes for NetComm Agent 4.0

This document describes the Cumulocity agent package for the NetComm Wireless NTC-6200 and the NetComm Wireless NTC-140W router.

Supported functionality

The agent supports the following functionality:

  • Bootstrap and registration of the router in Cumulocity.
  • Reporting of model, serial number, firmware version and installed software.
  • WAN, LAN and DHCP configuration.
  • Remote software and firmware installation and upgrading as service through the ipkg package manager.
  • System resource monitoring.
  • GPS-based location reporting.
  • Reporting GPIO pin readings (analog input) as measurements.
  • Raising and clearing alarms based on whether a GPIO pin (digital input) is open or closed in a circuit, including debouncing.
  • Remote controlling of GPIO pins (digital output) from Cumulocity.
  • Editing the router configuration.
  • Managing router configuration snapshots.
  • Remotely executing commands via device shell interface.
  • Sending event notifications as alarms.
  • Modbus-RTU and Modbus-TCP support for remotely managing Modbus devices from Cumulocity.
  • Lua plug-in API for rapid development of IoT applications.
  • Configuring and displaying of agent settings on the router's web user interface.
  • Get and put device configuration.
  • View system, ipsec and agent log files.
  • VNC remote access.
  • MQTT as alternative communication protocol.

Known limitations and bugs

  • The time on the router and on the server may not be fully in sync, hence you may see updates (e.g., alarms, events) that occur "in future". This is also the reason that it may take a while until the "Location" and the "Measurement" tab appear for new devices.
  • Only WAN profile 1 is supported. To set APNs, the "auto APN" mode on the device needs to be disabled.
  • Under some circumstances, a command sent to the device may be lost while switching between SMS and IP mode.

System requirements

The agent was tested on an NTC-6200 device with firmware version 2.0.36.10. For remote configuration of WAN parameters, you need a SIM card with SMS function. Currently, GSMA OneAPI (e.g., on Ericsson DCP), OpenIT and Jasper Wireless are supported APIs for SMS providers. Please contact support for connecting to an SMS provider.

Agent version 3.2.0 and up require backend minimum version 7.20 for multip-XID support.

Agent versions 2.3 and up require Cloud Fieldbus 4. They are not compatible with earlier versions of the Cloud Fieldbus application.

Agent versions 2.1.10 and up require at least Cumulocity 6.10 to support the new log viewer.

Installing the agent

The agent will automatically start after installation and the router can then be registered with Cumulocity. Subsequent upgrades or downgrades can be performed remotely via the agent's software management feature, or locally via the router's web portal.

When upgrading from versions older than 2.1.1, the device needs to be re-registered.

Using the agent

For information on using the agent, please visit the NetComm Agent User's Guide.

History

4.0.2

Agent Software, CA certificate bundle, VNC Proxy. Changes:

  • Agent is started/stopped directly after activating/deactivating it in Netcomm-WebUI
  • Agent is not started after device boot, when it was deactivated in Netcomm-WebUI
  • Created ntcagent folder is removed, when the Agent is completly de-installed
  • Temporary created files are deleted after usage

4.0.1

Agent Software, CA certificate bundle, VNC Proxy. Changes:

  • Agent waits after device boot for NTP synchronization before proceeding.
  • Supports now timer intervals smaller than 200 ms.

4.0.0

Agent Software, CA certificate bundle, VNC Proxy. Changes:

  • Add support for server certificate verification.
  • Add MQTT support as an alternative protocol alongside HTTP.
  • Support for VNC remote access.

3.2.2

Download link. Changes:

  • signal: report RSRP signal strength instead of RSCP when using 4G network.
  • integrate: use RDB uboot.hw_id as name when creating device.
  • modbus: disable Modbus-RTU support when model is NTC-140W.
  • modbus/mbbase: write modbus response values to agent log for easier troubleshooting.
  • [fix]modbus: fix regression bug introduced in 3.2.0 that reading is offset by 1 when data model doesn't start from number 1.

3.2.0

Download link. Changes:

  • ntcagent: Use file backed buffering for sending measurement, events, etc.
  • [fix]Modbus: write partial holding register crash in 3.1.6.
  • Query pending operations at boot time.
  • [fix]Makefile: separate LDLIBS for smsagent so smsagent build correctly and without unnecessary dependencies.
  • [fix]ntcagent: remove trailing slash in server URL so URL with trailing slash also works.

3.1.6

Download link. Changes:

  • [fix]Modbus: read per contiguous block.
  • [fix]lua/config: save configuration doesn't have effect.
  • ntcagent/postinst: set default serial port to /dev/ttyAPP4.
  • Modbus: add mbmanager so change serial configuration no longer requires a reboot.
  • [fix]lua/net: filter out deliveryType=SMS for configuring WAN operation.
  • Modbus: shorten modbus-TCP timeout from 50 sec to 10 sec.
  • [fix]Modbus: transmit rate not working because msg composing improperly.
  • [fix]Modbus: set byte timeout to 1 sec for getting slow Modbus-RTU to work.
  • [fix]lua/gps: use correct format DDDMM.MMmmm instead of DDMM.SSsss for GPS position.

3.1.2

Download link. Changes:

  • fix: fragile start-up process when send fails after register templates.
  • fix: Fixed one-hour off issue because of DST in logviewer.
  • Raise alarm when modbus slave reading fails.
  • fix: in logview get last N lines instead of first N lines in the given timeframe.
  • Use decimal instead of hex for LAC for OpenCellID to work.
  • Add RDB dump support.

3.0.0

Download link. Changes:

  • Add measurement poll support.
  • Implement modbus-RTU support for Cloud Fieldbus 4.
  • Add timestamp to description of uploaded configuration snapshot.
  • Report GPS fix on boot.
  • Add support for serial number in registration.
  • Disallow removing agent from Cumulocity Software Management.

2.3.6

Download link. Changes:

  • fix: not respect multiplier, divisor and decimalPlaces definition in FieldBus 4 when sending event.
  • string update: use generic IoT tokens instead of Cumulocity.

2.3.5

Download link. Changes:

  • Full support for fieldbus 4.
  • fix: Unintentionally include device credential when uploading configuration.
  • fix: Device shell plugin for operations that restart agent/device.
  • fix Unexpectedly restarting of the agent when set log level via device shell.
  • fix: Duplicate events and incorrect status updates
  • fix: Operation of set register for first holding register hangs

2.2.6

Download link. Changes:

  • GPIO alarm status is updated on device start.
  • GPIO debouncing fixes.
  • Performance and reliability improvements for operations.
  • Device Shell robustness improvements.
  • Modbus stability improvements and corrections.
  • Log rotation and log quota setting (through RDB parameter service.cumulocity.log.quota).
  • Remote log viewing of ipsec.log.
  • Log API for Lua.

2.1.10

Download link. Changes:

  • Crash fix
  • Configuration file tar bar and configuration text save fixes
  • Log viewer
  • Support for breakpad (crash tool)
  • Detect wrong plug-in name in configuration
  • Removed timeouts in software manager
  • Remove agent log file after install new version

2.1.8

Download link. Changes:

  • Save MSISDN number fix
  • Memory leak fix
  • Configuration file tar bar

2.1.6

Download link. Changes:

  • Configuration snapshot support (requires Cumulocity 6.9).
  • Sending event notifications as alarms.

2.1.4

Download link. Changes:

  • Operator name in "Info" page is now correctly displayed.
  • Clear credentials button in web UI works now correctly.