IoT Edge Router Getting Started Guide Published on Silver Spring Networks STAGE (

Transcription

1 IoT Edge Router Developer Kit Build your own edge application Order a Developer Kit [1] 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. Overview The IoT Edge Router Developer Kit allows third parties to rapidly develop solutions for the Silver Spring Data Platform utilizing the IoT Edge Router. Architecture The diagram below shows the reference architecture of how the IoT Edge Router Developer Kit is connected with sensors over BT/BLE/ZigBee and with the Data Platform over internet. 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. Note that, for connecting for ZigBee devices, a USB dongle is required for the IoT Edge Router. Terminology BLE Tag A BLE tag is a small device powered by battery or USB that emits a Bluetooth low energy (BLE) signal. A BLE tag can be paired with the IoT Edge Router to collect sensor data from sensors and Page 1 of 11

2 send to the Silver Spring Data Platform. Snappy Ubuntu Core Snappy is a lightweight version of Ubuntu. It can be used to develop secure Linux app packages known as snaps. Snap A Snap is a self-contained Linux application package which can be updated without affecting the rest of the system. The IoT Edge Router runs the Ubuntu Core Snappy environment. Developers can develop snap applications to run on the IoT Edge Router. CoAP Application Messaging Protocol Silver Spring Networks' Internet of Things (IoT) networking service that enables cities, utilities, businesses, and citizens to connect a wide range of intelligent devices and sensors to a Silver Spring network. Sensor devices communicate using the Constrained Application Protocol (CoAP). Communications with end devices is facilitated through the Gateway CoAP API. The IoT Edge Router supports CoAP for communication between devices and sensors and the Silver Spring Data Platform. IoT Edge Router Developer Kit This shows the items included in your new IoT Edge Router Developer Kit. Page 2 of 11

3 What is in the IoT Edge Router Dev Kit Due to regulatory issues the antenna and power supply are sold as separate catalog items however you must purchase the accessory kit. The IoT Edge Router and Accessory Kit combined contain the following components: IoT Edge Router Antenna 5VDC power supply and international adapters Note: The IoT Edge Router has two variants (for USA and Australia). Be sure to buy one approved for use in the country where you will deploy it. The Accessory Kit includes the antenna and power supply. Additional Recommended Hardware The following additional items are required to install the IoT Edge Router Ethernet cables Page 3 of 11

4 Four port switch USB keyboard Mouse Laptop with an SSH Client for Linux access (for example, Mac, Windows PC with Bitvise Tunnelier or PuTTY, or Linux PC) TI Sensor Tag CC6250 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 Silver Spring 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 Silver Spring 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 four 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: Ror 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 Silver Spring 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 Silver Spring 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). Page 4 of 11

5 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 Consderations Bandwidth 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 ms, and you should expect ms per hop across the Silver Spring 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, Silver Spring recommends that you use an open source VPN (such as OpenVPN) for your sessions. Silver Spring recommends that you use User Datagram Protocol (UDP) (rather than lossy links). Transmission Control Protocol (TCP) is supported, but using it contributes to latency IoT Edge Router Status LED Information The IoT Edge Router includes a dual color LED (green and red) located near the HDMI port. Note: LED functionality is not currently supported. Setting up the Hardware To connect and test the IoT Edge Router, the following steps are required. Step 1: Power on the device and verify LED status 1. Attach the antenna (provided in the IoT Edge Router kit). Page 5 of 11

6 2. The IoT Edge Router includes a dual color LED (green and red). Connect the IoT Edge Router to an appropriate power supply (ensuring that the center pin from the power supply is positive). You should see red lights illuminate from inside the IoT Edge Router. 3. Verify that the LED status turns to green. Step 2: 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: a. Connect your IoT Edge Router to a computer using a standard Ethernet cable. b. Using a web browser, enter the IP address in the URL field. 3. Wait briefly for the IoT Edge Router to boot up. Note: Boot up can take about seconds (including not only the 20 seconds for the radio to power up). 4. If needed, select a different network ID in the Network ID dropdown list and country in the Country Code dropdown lists. Page 6 of 11

7 Step 3: Connect to the Internet 1. Connect an Ethernet cable from the IoT Edge Router to the device you are using to communicate with it. 2. Confirm that you see the Link LED illuminate and flash (with traffic). 3. To verify end to end connectivity, verify that you can ping a well known host (such as one of Google s DNS servers, ) from your device to the Internet. Page 7 of 11

8 Connecting and Testing Your Device (General) IoT Edge Router testing should be performed with a generic scenario in mind. Part of proper testing of this solution requires some pre provisioning of the third party device. The device/client must establish a connection (using TCP) to the host/server application or initiate communications (using UDP). Once this connection or communication is initiated, two way communication can take place. To connect and test your device 1. Attach the antenna (provided in the IoT Edge Router kit). 2. Connect the IoT Edge Router to an appropriate power supply (ensuring that the center pin from the power supply is positive). You should see red lights illuminate from inside the IoT Edge Router. 3. Verify that your IoT Edge Router has been configured to call your host application or third party cloud. 4. Connect an Ethernet cable from the IoT Edge Router to the device you are using to communicate with it. 5. Confirm that you see the Link LED illuminate and flash (with traffic). 6. Verify that your device received an IPv4 address from the Dynamic Host Configuration Protocol (DHCP) host on the IoT Edge Router by interrogating the device. 7. Verify end to end connectivity. 8. Verify that you can ping a well known host (such as one of Google s DNS servers, ) from your device out to the Internet. 9. The host application should now be able to send traffic across the network. 10. If you experience any problem with the above process, please refer to the troubleshooting section of this document. Setting the Mode The IoT Edge Router can be run in one of three modes: 1. Client - turns off ethernet as being a dhcp server and turns it into a dhcp client so you can use your local internet access 2. Edge Router - edge mode using rf mesh as backhaul 3. WAN To run in Client mode, issue the following command: sudo edgerouter -m client To run in Edge Router mode, issue the following command: sudo edgerouter -m edge Shell Access and Secure File Copying You need an IoTR certificate for SSH/SCP communications. With the certificate/private key, you can Page 8 of 11

9 use SSH to connect with the IoT Edge Router, or use Secure Copy (SCP) to transfer files to and from the IoT Edge Router. Once logged into the IoT Edge Router, you can use tcpdump to monitor traffic across the Silver Spring 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. Ubuntu Linux Security related patches are installed automatically as available when secure boot occurs. CAUTION: Due to potential security issues, you should use this method with caution. For guidance, consult with your Silver Spring representative. The IoT Edge Router is based on a Olimex LIME2 platform (see [2]) running Linux Ubuntu LTS (see [3]); specifically, the Armbian build (see [4]). All of the above linked pages provide very good online community forums and support. To use shell access or secure file copying with the IoT Edge Router 1. Attach the antenna (provided in the IoT Edge Router kit). 2. Connect the IoT Edge Router to an appropriate power supply (ensuring that the center pin from the power supply is positive). You should see red lights illuminate from inside the IoT Edge Router. 3. Verify that your IoT Edge Router has been configured to call your host application or third party cloud. 4. Connect an Ethernet cable from the IoT Edge Router to the device you are using to communicate with it. 5. Login to the IoT Edge Router using: user name: dev password: starfish 6. On the Linux machine, put the cert in your ~/.ssh folder. When using SSH operations, one option is to use ssh instead of having to specify the certificate every time on the command line. Setting up the Software Logging in to the IoT Edge Router For version 2.5, if you need to log in to the IoT Edge Router, use the following credentials: user name: dev password: starfish Linux Development Environment Silver Spring Networks 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. Page 9 of 11

10 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 [5]. 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: [6]. CoAP Application Messaging Protocol Starfish is the Silver Spring Internet of Things (IoT) networking service that enables cities, utilities, businesses, and citizens to connect a wide range of intelligent devices and sensors to a Silver Spring 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 [7]. Following is an example JavaScript: var coap, server = require('coap') = 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() }) Page 10 of 11

11 Reference Application You might find the IoT Edge Router Example Application [8] 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 [9] section of this portal and retrieve your ClientID and Secret from the Account Settings tab. See the resource link to the API documentation above. 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: Installting 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 A: Troubleshooting Appendix B: IoT Edge Router Extensibility Using Ubuntu Core Source URL: Links [1] [2] [3] [4] [5] [6] [7] [8] [9] Page 11 of 11