IoT Edge Router Getting Started Guide

IoT Edge Router Developer Kit

Build your own edge application. Order a Developer Kit
This Getting Started Guide will quickly get you up and running with the IoT Edge Router and put you on the path toward building your own new exciting applications.
Note: Itron no longer supports the miniAP and strongly recommends that developers use the IoT Edge Router instead. 

Architecture

The following image shows how Itron can provide end-to-end connectivity. Sensor data is delivered through the Network Platform to the Data Platform over CoAP and the Data Platform enables data access through REST APIs to back office applications. The IoT Edge Router can be run in three modes:

  • CLIENT mode:  Turns off Ethernet as being a DHCP server and turns it into a DHCP client so you can use your local Internet access
  • EDGE mode: Edge mode using RF mesh as backhaul
  • WAN mode: Replaces the AP or miniAP for backhaul over Ethernet

Each of the three modes are addressed in the diagram below. How you connect your IoT Edge Router depends on which mode you are using.

 

Working configuration scenarios

  • Ipv4 modem replacement –  limited to the range of 192.168.16.2 – 127 for network IP devices.
  • Ipv6 modem replacement – in configured iot prefix /64
  • WAN mode (including Milli devices) - provides mesh data backhaul to back-office software
  • Client mode - ethernet acts as DHCP client for desktop development with connection to the internet

 

Current known limitations

  • No software watchdog available.
  • No OTA snap updates
  • No Factory reset
  • No ability to update the kernel image
  • No ability to provide automatic NIC FW updates (can only update NIC FW using ssh & manual update)
  • No ability to change IoTR Edge Static IP address or the DHCP Range in Edge mode. IoTR will have IP address 192.168.16.1 and is limited to network device IP addresses in the range 192.168.16.2 – 127.
  • Limited web portal configuration options
  • Limited remote SSH Access
  • Limited ability to switch networks – requires manual configuration
  • Launching ssnmode.confstat application to change modes via different terminals may output unusable info. Also various keyboard input issues related to this application.
    • Alternate method to change mode if ssnmode.confstat is not performing as expected (due to keyboard or terminal display).
    • Edit /var/snap/ssnmode/current/iotrswitch.conf file and change the desired mode.
    • Then restart the service ($ sudo systemctl restart snap.ssnmode.ssnmode.service).

 

Using the IoT Edge Router Admin UI

The IoT Edge Router Admin UI includes the following four sections:

Section 1

Displays device information for IoT Edge Router Linux and the IoT Edge Router NIC

  • Distribution: Displays the IoT Edge Router Linux Distribution, which is Ubuntu 16.04 and the associated kernel version.
  • SW Build Number: Displays the current software release flashed into the IoT Edge Router.
  • NIC RF MAC: Displays the device MAC address.
  • NIC FW Image: Displays the NIC firmware version.
  • Start Word: The Start Word helps enable wireless communications for all Itron devices in the utility network. All devices in a specific Itron network (a master bridge and all associated slave bridges, for example) must share the same start word.
  • Device Type: Displays the device type; this is 58, which corresponds to the IoT Edge Router integrated Linux device.

 

Section 2

Allows the user to provision the IoT Edge Router NIC by setting the Network ID and the Country Code

  • Network ID: Displays the Network ID, which uniquely identifies the network to which a node (NIC) belongs, and enables the intelligent endpoint to be detected, identified, and tracked among all endpoint devices. A device can communicate only with another device with the same Network ID. Every device is configured with a 16-bit network device ID, with allowance to have 65,535 unique network IDs.
  • Country Code: Displays the country code, which is a unique identifier that describes the country of operation for the device. This code (ISO country code) identifies the unique features and restrictions available in a particular region.

All devices must have the same Network ID, Country Code, and Start Word in order to be part of the same network.

Section 3

Allows the user to test IoT Edge Router connectivity by executing a network ping test

  • Network Ping Test: Allows the user to run a ping test.

 

Section 4

Allows the user to scan the mesh nodes

  • Mesh NIC Scanning Results: Displays the IoT Edge Router scanning results.
  • Mesh Milli Scanning Results: Displays all Milli5 HDKs scanned if Milli Mesh is enabled.

 

Setting up the Hardware

To connect and test the IoT Edge Router configured in Edge mode to the Itron back office, you will need: 

  • A MiniAP and the IoT Edge Router configured in Edge mode OR
  • Two IoT Edge Routers 
    • One configured in Edge Mode
    • One configured in WAN mode - this configuration provides data backhaul to back office software to connect any IoT Edge Router in Edge mode and any Milli Dev Kit.

 

 

Step 1: Setup MiniAP if you will be running in Edge Mode connecting through a MiniAP

  1. If you will be running in Client or WAN mode skip to Step 2.
  2. For Edge Mode Power on the MiniAP per Getting Started Guide.

 

Step 2: Power on the IoT Edge Router device

  1. Attach the antenna (provided in the IoT Edge Router Accessory kit).
  2. Connect the IoT Edge Router to an appropriate power supply (ensuring that the center pin from the power supply is positive). You may see a red glow from inside the IoT Edge Router.

 

Step 3: Configure the country code

  1. Because radio frequency assignment vary internationally, you need to verify or set the country for your IoT Edge Router depending on the intended deployment location.
  2. To verify or set the country for your IoT Edge Router:
    1. Connect your IoT Edge Router to a computer using a standard Ethernet cable, and set the IPv4 address to that ethernet interface on your computer to 192.168.16.2. Since the IOT Edge Router ships with an IP address of 192.168.16.1, you need your computer on the same segment but different IP address than the IoT Edge Router. Since the IOTR ships with an IP address of 192.168.16.1,
    2. Using a web browser, enter the IP address 192.168.16.1 in the URL field.

 

 

  1. Wait briefly for the IoT Edge Router to boot up.
    Note: Boot up takes about two minutes (including the time for the radio to power up).

 

 

  1. Select the appropriate country code from the Country Code dropdown list.  Use the country codes described in the table in "IoT Edge Router Compliance Information" later on this page. These are based on the ISO Country Codes. The country code will be used to configure the device for the proper country frequency band.
  2. If needed, enter an alternate Network ID in the box. Note that, for Starfish Stage environment which is used by the Itron Developer Program, the Network ID needs to be 1711 (the default value for a new IoT Edge Router).
  3. When the browser's 'Waiting' alert box closes, the IoT Edge Router has been provisioned.

Note: if you are running in Edge mode and have already set up the miniAP or IoT Edge Router in WAN mode, then you should see the MAC ID for the miniAP or IoT Edge Router in WAN mode listed in the “Mesh NICs Scanning Results” field, as shown in the configuration screenshot below.  This will be true only if both the IoT Edge Router and AP are on the same Network ID

 

 

Step 4: Set the Mode

  1. With a computer connected directly to the IOT Edge Router in step 3.2 above, use PuTTY with the host name set to 192.168.16.1.

 

 

Once the ssh window is displayed login using the following credentials:

  • User: dev
  • Password: starfish

 

 

By default, the IoT Edge Router is configured in Edge mode.
To change the configuration to WAN mode, use the following command:

dev@ssniotr:~$sudo ssnmode.confstat
If you are alerted in the command line that the window size is too small, increase stty windows using the following command:
dev@ssniotr:~$stty columns 100 rows 30

 

 

 

Note: Press F5 as needed to refresh this window. 

 

 

To configure the IoT Edge Router in WAN mode

Update the contents of the configuration MODE window with WAN, arrow down to <RUN> and press Enter or Return.

Press F5 to refresh current settings. You should see that mode is WAN - inactive in red.

To configure the IoT Edge Router in EDGE mode
Update the contents of the configuration MODE window with EDGE, and press Enter or Return when the cursor points to <RUN>.

To configure IoT Edge Router in Client mode
Update the contents of the configuration MODE window with CLIENT, and press Enter or Return when the cursor points to <RUN>.
The on-board LED indicates the IoT Edge Router mode status for different modes as follows:

  • EDGE mode: Solid RED
  • CLIENT mode: Solid ORANGE (combination of RED and GREEN)
  • WAN mode: Solid GREEN
  • WAN-FAILOVER mode: Blinking GREEN (indicating the IoT Edge Router is trying to make WAN mode active).

 

To exit the ssnmode.confstat application, press F1.

Step 5: Connect to the Internet

  1. If you are running in Client or WAN Mode continue with Step 5 otherwise skip to Step 6.
  2. Connect an Ethernet cable from your IoT Edge Router to the device (typically a router or ethernet connection with DHCP server)  you are using to communicate over the internet and power up the IoT Edge Router.
  3. Determine the IP address that has been assigned to the IoT Edge Router.
    1. If on a corporate network work with IT to determine the IP address.
    2. If it is a local router for which you have access and know the router's IP address you can use the local router admin tool. This can typically be accessed by entering the local router IP address in a browser. NOTE: the IoT Edge Router's MAC address will start with "00-13" if searching by MAC address.
  4. ​Enter the new IP address of the IoT Edge Router on the network into a browser. This turns on the IOT Edge Router's radio.
  5. After a few seconds the browser should bring up a diagnostic page which lets you see the country code, network ID, etc.
  6. After 30 seconds, check the status LED to confirm it is solid orange in case of Client Mode and solid green for WAN Mode. The IoT Edge Router continuously checks for WAN Mode every 30 seconds.
  7. Expect at least three minutes for the IoT Edge Router to register with the mesh network before a connection with the internet can be established.

 

Step 6: Verify Connectivity

  1. Log in to Unix shell account via the console by attaching USB keyboard and HDMI monitor to the IoT Edge Router (note: this version does not support the act of plugging in the HDMI cable after the IoT Edge Router is powered on. Plug the HDMI cable in first, then power-on/reboot the device). 
    OR
    via Ethernet by attaching your computer with a SSH terminal client to the IoT Edge Router using an Ethernet cable.
  2. Run sudo.ssnmode.confstat and press F5 again. The mode should display WAN - active, Edge - active, or Client - active in green.
  3. Verify connectivity by pinging a well-known host (such as one of Google's DNS servers, 8.8.8.8) from your device to the Internet.
  4. Verify DNS availability by pinging a well-known host (such as google.com) from your device to the Internet.
  5. Confirm connection to the Itron Data Platform.

 

IoT Edge Router is now configured.

Once logged into the IoT Edge Router, you can use tcpdump to monitor traffic across the Itron NAN (on interface tun6 or, for IPv4 traffic only, on interface b4 or eth for the Ethernet side). You can also create shell scripts, Python scripts, applications, and so on. 

If you are in the process of setting up your Milli Dev Kit, return to the Milli Getting Started page. Alternatively, proceed to step 2, Milli Hardware Setup and Provisioning.

The IoT Edge Router is based on a Olimex LIME2 platform (see https://www.olimex.com/wiki/A20-OLinuXino-LIME2) running the ARMBIAN variant of Linux Ubuntu 16.04 LTS (see https://www.ubuntu.com).

How it Works

The IoT Edge Router exposes interfaces that can be used for network connectivity of third‐party devices such as sensor gateways that support Ethernet as a form of backhaul.

Once the IoT Edge Router is connected and powered up, it can be connected to the network in the same way as any other Itron NIC‐enabled device. The IoT Edge Router can be provisioned with the IP address of the AFTR in the back office (note that pre‐provisioning is not provided during device manufacturing), and it registers with the nearest Access Point (where DNS and other back‐office services complete the registration process). The AFTR is also provisioned with an IPv4 network address translation (NAT) pool that is used for devices connected to the IoT Edge Router. These steps complete device registration for the Itron network.

The third‐party device will most often call its own third‐party cloud, and that access is provided by the AFTR.

 

Connecting Third-Party Devices Over Ethernet

This section describes the general methods for connecting third‐party devices to the IoT Edge Router using the Ethernet port (per protocol and configuration for your devices). To enable direct communications with your back office or cloud software, consider the following:

 

  • For Native IPv6, StateLess Address Auto Configuration (SLAAC)
    • For zero touch/configuration installations.
    • Dynamic Domain Name System (DDNS) compatible.
    • Communications can be initiated to or from the device, back office, or cloud.
    • Requires Itron support at the WAN router/AP for the IoT Edge Router prefix, and for the routing protocol (for example, IPv6 RIP).
  • For IPv6, static prefix/subnet/interface identifier
    • Requires configuration of the IPv6 prefix/subnet/host identifier, router, and Domain Name System (DNS).
    • DDNS compatible.
    • Communications can be initiated to or from the device, back office, or cloud.
    • Requires Itron support at the WAN router/AP for the IoT Edge Router prefix, and for the routing protocol (for example, IPv6 RIP).
  • For IPv4 Dynamic Host Configuration Protocol (DHCP) or static, private address/dynamic NAT
    • For zero touch/configuration installations.
    • Communication must be initiated from the device to the back office or cloud (GRE/VPN can be used).
    • Requires a Dual‐Stack Lite AFTR/CGN appliance in the back office (for example, A10 vThunder).

 

Connectivity Capabilities and Considerations

 

Connectivity Options Supported

Prior to testing your devices (for both your hardware and software solutions), including accounting for any boundary conditions, consider the following regarding what the IoT Edge Router currently supports:

  • IPv4 to the public Internet.
  • Ethernet physical connections (Serial and HDMI output not supported at this time).

 

Connectivity Capability and Test Considerations

  • Bandwidth on the IoT Edge Router Dev Kits is limited to 10 kbps with bursts of 15 kbps You should test for sparse network conditions, which could be as low as 5–10 kbps.
  • Expected latency depends on the wide area network (WAN). Typically, startup occurs within 1000–2000 ms, and you should expect 50–75 ms per hop across the Itron network.
  • IoT Edge Router uses IP addresses created through network address translation (NAT) (not public IP addresses).
  • Devices initiate connections to the Internet. If a secure connection to a private cloud is required, Itron recommends that you use an open source VPN (such as OpenVPN) for your sessions.
  • Itron recommends that you use User Datagram Protocol (UDP) (rather than lossy links).
  • Transmission Control Protocol (TCP) is supported, but using it contributes to latency.

 

IP Address Assignment Considerations

  • For IoT Edge Router version 2.5: The DHCP server on the IoT Edge Router uses the full 192.168.16.2 through 192.168.16.255 IP address range. For devices connected to the IoT Edge Router, assign static IP addresses from the higher part of the range (such as 192.168.16.200 through 192.168.16.255).
  • For IoT Edge Router versions later than 2.5:  The DHCP server on theIoT Edge Router ruses 192.168.16.2 through 192.168.16.127 IP address range.  For devices connected to the IoT Edge Router requiring static IP addresses, assign these from the range 192.168.16.128 through 192.168.16.255.
  • The subnet mask value is set for 255.255.255.0.
  • The gateway value is set for 192.168.16.1.

 

Milli Mesh Considerations

  • Due to limitations of Milli mesh using devices running Itron firmware 3.12.7001, “EU868” and “FRA” country codes are not supported, and, therefore, the regions serviced by those country codes do not support Milli.
  • Following are the mappings of consolidated EU country codes to the countries and regions they support. Developers should apply these codes as needed when provisioning their devices in the provisioning portal where they set the country code, network ID, and so on, taking into account whether or not Milli mesh is supported in each case:
    • Milli mesh available:
      • EU873: GBR, IRE, SWZ, SWE, POR, LUX, ISL, HUN, FIN, EST
      • EU876: DEN, ALB, MDA, NOR, SVN
    • Milli mesh not available:
      • EU868: FRA, TUR, ESP,AUT, BEL, BGR, HRV, CYO, CZE, DEU, GRC, ITA, LVA, LIE, LTU, MLT, NLD, POL, ROU, SVK, FRA: Paris

Linux Development Environment

Itron has adopted the Canonical Ubuntu Core distribution for the IoT Edge Router. The Ubuntu Core OS is a lightweight, transactionally‐updated OS where every application is installed confined from others as a Snap package. It is designed to run securely with faster and more reliable security guarantees for the apps and users.

Application deployment is handled by Canonical Snappy Ubuntu Core, a small, transactional version of the Ubuntu full version. The IoT Edge Router supports Snap applications that are developed using Ubuntu standard tools. For more details, see https://snapcraft.io/.

For demos and related information about Github Snapcrafts for battery low energy (BLE) and Amazon Web Services (AWS) Open Source Snapcraft Apps, refer to the suggested information source: https://github.com/snapcore/snapcraft/tree/master/demos.

 

CoAP Application Messaging Protocol

The Itron Internet of Things (IoT) networking service that enables cities, utilities, businesses, and citizens to connect a wide range of intelligent devices and sensors to an Itron network. Devices can be used to address requirements in a variety of sectors, including water, energy, food, transportation, and safety.

In a Starfish network, sensor devices communicate using the Constrained Application Protocol (CoAP). Communications with end devices is facilitated through the Gateway CoAP API.

Location: /usr/local/SSN/SDK/CoAP

Constrained Application Protocol (CoAP) global libraries are installed with Node Package Manager for Node.js.

Reference libraries and examples can be found at https://github.com/mcollina/node-coap. Following is an example JavaScript:

 

var coap        = require('coap')

, server      = coap.createServer({ type: 'udp6' })

server.on('request', function(req, res) { res.end('Hello ' + req.url.split('/')[1] + '\n')

})

// the default CoAP port is 5683 server.listen(function() {

var req = coap.request('coap://[::1]/Matteo')

req.on('response', function(res) { res.pipe(process.stdout) res.on('end', function() {

process.exit(0)

})

})

req.end()

})

 

 

Troubleshooting

This section provides troubleshooting information for the IoT Edge Router.

 

Ensuring the IoT Edge Router is Running Correctly

To ensure that your IoT Edge Router is running correctly as configured, use SSH to access it. You should be able to ping the AFTR peer (fd1e:d0d6:d81d:e070::76), and you should be able to ping outside through IPv4 (for example, by pinging 8.8.8.8).

As highlighted in the sample output below, look for the following for your device:

  • tun6 should be up and have a fully-qualified IPv6 address
  • b4 should be up, and be connected to the AFTR peer
 
root@ssniotr:~# ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 16436 qdisc noqueue state UNKNOWN group default
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
    inet6 ::1/128 scope host 
       valid_lft forever preferred_lft forever
2: bond0: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN group default
    link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
3: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 02:8c:06:c1:21:e6 brd ff:ff:ff:ff:ff:ff
    inet 192.168.16.1/28 brd 192.168.16.15 scope global eth0
    inet6 fe80::8c:6ff:fec1:21e6/64 scope link 
       valid_lft forever preferred_lft forever
4: tunl0: <NOARP> mtu 1480 qdisc noop state DOWN group default
    link/ipip 0.0.0.0 brd 0.0.0.0
5: tun6: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc htb state UNKNOWN group default qlen 500
    link/none 
    inet6 fdc9:ccbe:1dc7:14:213:5003:78:fc6e/64 scope global
       valid_lft forever preferred_lft forever
    inet6 fe80::213:5003:78:fc6e/64 scope link 
       valid_lft forever preferred_lft forever
6: ip6tnl0: <NOARP> mtu 1452 qdisc noop state DOWN group default
    link/tunnel6 :: brd ::
9: b4: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1440 qdisc noqueue state UNKNOWN group default
    link/tunnel6 fdc9:ccbe:1dc7:14:213:5003:78:fc6e peer
fd1e:d0d6:d81d:e070::76
    inet 192.0.0.2 peer 192.0.0.1/32 scope global b4
    inet6 fe80::8c:6ff:fec1:21e6/64 scope link 
       valid_lft forever preferred_lft forever

 

 

Enabling Routing for IPv6 Prefixes

This section provides some basic RIPng configuration methods that can be useful for addressing, in particular, issues with timers that you might encounter 

You must apply Cisco tunnel router configuration to enable RIPng on each IPSec tunnel interface in order to enable routing for the IPv6 prefix as the following example shows. Note that you also need to set up routing on the outgoing interface (using OSPF, Static routes, or similar means).

interface Tunnel1993
 description "Bridge 001350fffe101993"
 no ip address
 ipv6 enable
 ipv6 rip ripng enable
 tunnel source GigabitEthernet0/1
 tunnel mode ipv6ip
 tunnel destination 192.168.1.93

You must also set the RIP timers. By default they are too chatty for cellular connections. Set this for both Cellular and Ethernet APs if you have a mixed deployment. The defaults are fine for an all Ethernet deployment (this is rare currently, however).

ipv6 router rip RIP4IOT
timers 180 720 540 1440
 

 

No Connectivity Through the MiniAP

If you are using the miniAP for network communications, if the IoT Edge Router cannot see the miniAP in its nodeq, then it has no means to connect back to the Internet. On the configuration page (using the browser UI) you should see the miniAP's MAC ID listed on the “NIC nodeq”, assuming both the IoT Edge Router and AP are on the same Network ID. If you do not, this needs to be corrected.

 

Issues Using Snap Applications on the IoT Edge Router

If you encounter issues using snap applications on the IoT Edge Router, see https://tutorials.ubuntu.com/ and search for SNAP for their tutorials on SNAP packaging.

 

Reference Application

You might  find the IoT Edge Router Example Application provided with this portal to be a useful reference. Source code and documentation are provided. 

 

API Access

To use APIs, you will need API key credentials.  Go to the My Account Overview section of this portal and retrieve your ClientID and Secret from the Account Settings tab. See the resource link to the API documentation above.

 

Using Snaps to Install Software on the IoT Edge Router

For anyone wanting to install software on an IoT Edge Router, it should be packaged as a snap (https://snapcraft.io/), installable on Ubuntu Core. For a public list of available snapped apps, see https://uappexplorer.com/snaps.

Under Ubuntu Core, there is an official Docker host snap (from Docker, Inc.) which can be installed (https://uappexplorer.com/snap/ubuntu/docker). And then any software that is a Docker container can be installed. For a list of published Docker app containers, see https://hub.docker.com/.

To install custom software, it needs to be packaged as a snap or as a Docker container. There should be no exceptions.

Root access, changing configuration, and installing packages and libraries to the current IoT Edge Router host OS (Ubuntu 16.04) is not supported.

In the very near future, the Host OS will not be Ubuntu 16.04; instead it will be Ubuntu Core.

To ensure compatibility with future production releases of the IoT Edge Router, everything must be done through Ubuntu Core.

Ubuntu Core runs as a daemon under Ubuntu 16.04. Snaps can be installed on Core (whether it is a daemon running under a host OS or natively). Itron  recommends developing on a local or cloud VM instance whenever possible before installing a snapped application on the embedded (IoT Edge Router) target.

Several steps could be needed. For example, test/develop on Core as a daemon local/cloud instance, then as a native core local/cloud instance, and as documented on https://snapcraft.io/, including using devmode first before moving to strict confinement.

 

Additional References

 

IoT Edge Router Compliance Information

NAN1 Band
Country Code
HW
Frequency Band
Power (ERP) 
Power (EIRP) 
Countries
AUS
36
2
915-928
 
1 W
AUS
EU868
276
3
865-870
25 mW
 
AUT, BEL, BGR, HRV, CYP, CZE, FRA, DEU, GRC, ITA, LVA, LIE, LTU, MLT, NLD, POL, ROU, SVK, ESP, TUR
EU873
826
3
870-873
500 mW
 
EST, FIN, HUN, ISL, IRL, LUX, PRT, SWE, CHE, GBR
EU876
208
3
870-875.6
500 mW
 
ALB, DNK, MDA, NOR, SVN
SGP
702
2
920-925
500 mW
 
SGP
UAE
784
3
870-875.6
500 mW
 
UAE, SAU
USA
840
1
902-928
 
4 W
USA, CAN, JAM

 

Additional Information

More information is available in the IoT Edge Router 2.5 Installation and User Guide. Of particular interest to those referencing this page are:

Section 2: Installing the IoT Edge Router
               Interfaces
               Connecting Third-Party Devices
               Considerations for Testing
               LED Status Info
               Connecting and Testing Your Device
               Setting the Mode
               Shell Access and Secure File Copying
Section 3: Using the IoT Edge Router
               Logging in
               Connectivity Options
Appendix B: IoT Edge Router Extensibility Using Ubuntu Core
Appendix C: Specifications
Appendix D: Safety Information
Appendix E: Compliance Information