diff --git a/docs/assets/lora1.png b/docs/assets/lora1.png index f62b43f..d7fdd1c 100644 Binary files a/docs/assets/lora1.png and b/docs/assets/lora1.png differ diff --git a/docs/assets/lora18.jpg b/docs/assets/lora18.jpg new file mode 100644 index 0000000..75ddc53 Binary files /dev/null and b/docs/assets/lora18.jpg differ diff --git a/docs/assets/lora19.png b/docs/assets/lora19.png new file mode 100644 index 0000000..442dfff Binary files /dev/null and b/docs/assets/lora19.png differ diff --git a/docs/assets/lora7.png b/docs/assets/lora7.png index 79025b8..51936b9 100644 Binary files a/docs/assets/lora7.png and b/docs/assets/lora7.png differ diff --git a/docs/assets/lora8.png b/docs/assets/lora8.png index 0480c5a..69c8b3e 100644 Binary files a/docs/assets/lora8.png and b/docs/assets/lora8.png differ diff --git a/docs/assets/ttn1.png b/docs/assets/ttn1.png new file mode 100644 index 0000000..66bb3cc Binary files /dev/null and b/docs/assets/ttn1.png differ diff --git a/docs/assets/ttn10.png b/docs/assets/ttn10.png new file mode 100644 index 0000000..0dce685 Binary files /dev/null and b/docs/assets/ttn10.png differ diff --git a/docs/assets/ttn11.png b/docs/assets/ttn11.png new file mode 100644 index 0000000..98bf7af Binary files /dev/null and b/docs/assets/ttn11.png differ diff --git a/docs/assets/ttn12.png b/docs/assets/ttn12.png new file mode 100644 index 0000000..f0262e4 Binary files /dev/null and b/docs/assets/ttn12.png differ diff --git a/docs/assets/ttn13.png b/docs/assets/ttn13.png new file mode 100644 index 0000000..c7d8e89 Binary files /dev/null and b/docs/assets/ttn13.png differ diff --git a/docs/assets/ttn14.png b/docs/assets/ttn14.png new file mode 100644 index 0000000..8c81c2c Binary files /dev/null and b/docs/assets/ttn14.png differ diff --git a/docs/assets/ttn15.png b/docs/assets/ttn15.png new file mode 100644 index 0000000..2281274 Binary files /dev/null and b/docs/assets/ttn15.png differ diff --git a/docs/assets/ttn16.png b/docs/assets/ttn16.png new file mode 100644 index 0000000..7b13a3f Binary files /dev/null and b/docs/assets/ttn16.png differ diff --git a/docs/assets/ttn17.png b/docs/assets/ttn17.png new file mode 100644 index 0000000..0c6c369 Binary files /dev/null and b/docs/assets/ttn17.png differ diff --git a/docs/assets/ttn18.png b/docs/assets/ttn18.png new file mode 100644 index 0000000..7735c82 Binary files /dev/null and b/docs/assets/ttn18.png differ diff --git a/docs/assets/ttn19.png b/docs/assets/ttn19.png new file mode 100644 index 0000000..a5e1f4c Binary files /dev/null and b/docs/assets/ttn19.png differ diff --git a/docs/assets/ttn2.png b/docs/assets/ttn2.png new file mode 100644 index 0000000..4d91f94 Binary files /dev/null and b/docs/assets/ttn2.png differ diff --git a/docs/assets/ttn3.png b/docs/assets/ttn3.png new file mode 100644 index 0000000..5e49639 Binary files /dev/null and b/docs/assets/ttn3.png differ diff --git a/docs/assets/ttn4.png b/docs/assets/ttn4.png new file mode 100644 index 0000000..eb389da Binary files /dev/null and b/docs/assets/ttn4.png differ diff --git a/docs/assets/ttn5.png b/docs/assets/ttn5.png new file mode 100644 index 0000000..953e45d Binary files /dev/null and b/docs/assets/ttn5.png differ diff --git a/docs/assets/ttn6.png b/docs/assets/ttn6.png new file mode 100644 index 0000000..765637d Binary files /dev/null and b/docs/assets/ttn6.png differ diff --git a/docs/assets/ttn7.png b/docs/assets/ttn7.png new file mode 100644 index 0000000..6c761ea Binary files /dev/null and b/docs/assets/ttn7.png differ diff --git a/docs/assets/ttn8.png b/docs/assets/ttn8.png new file mode 100644 index 0000000..7893341 Binary files /dev/null and b/docs/assets/ttn8.png differ diff --git a/docs/assets/ttn9.png b/docs/assets/ttn9.png new file mode 100644 index 0000000..4f9c5b7 Binary files /dev/null and b/docs/assets/ttn9.png differ diff --git a/docs/index.md b/docs/index.md index 24c2f75..0a354ab 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,3 @@ -# LoRa on ARM mbed +# LoRa on Arm Mbed OS -[LoRa](http://lora-alliance.org) is a long range wide-area network technology that combines long range with low power consumption. This space contains documents on how to get started building LoRa networks and LoRa appliances using ARM mbed. +[LoRaWAN](http://lora-alliance.org) is a long range wide-area network technology that combines long range with low power consumption. This space contains documents on how to start building LoRa networks and LoRa appliances using Arm Mbed. diff --git a/docs/intro-to-lora.md b/docs/intro-to-lora.md index e737647..b4ab27d 100644 --- a/docs/intro-to-lora.md +++ b/docs/intro-to-lora.md @@ -1,139 +1,416 @@ -# Building your own private LoRa network +## Building your own private LoRa network -There is a lot of buzz about [LoRa](https://www.lora-alliance.org), a wide-area network solution that promises kilometers of range with very low power consumption, a perfect fit for the Internet of Things. Telecom operators are rolling out LoRa networks, but because LoRa operates in the [open spectrum](https://en.wikipedia.org/wiki/ISM_band), you can also set up your own network. This article discusses the requirements to build a private LoRa network and how to use the network to send data from an ARM mbed end-node to the cloud. +There is a lot of interest in [LoRa](https://www.lora-alliance.org), a wide-area network solution that promises kilometers of range with low power consumption, a perfect fit for the Internet of Things. Telecom operators are rolling out LoRa networks, but because LoRa operates in the [open spectrum](https://en.wikipedia.org/wiki/ISM_band), you can also set up your own network. This article discusses what you need to build a private LoRa network and how to use the network to send data from an Arm Mbed end node to the cloud. -**Note on LoRa vs. LoRaWAN:** Technically, we're building a LoRaWAN network in this article. LoRa is the modulation technique used (PHY), and LoRaWAN is the network protocol on top of the physical layer (MAC). +**Note on LoRa vs. LoRaWAN:** Technically, this article explains how to build a LoRaWAN network. LoRa is the modulation technique used (PHY), and LoRaWAN is the network protocol on top of the physical layer (MAC). -## Requirements +### 1. What you need A typical LoRa network consists of four parts: devices, gateways, a network service and an application: ![Topology of a LoRa network](assets/lora1.png)Topology of a LoRa network -For hardware, you need devices and gateways, similar to how you would set up a Wi-Fi network. Gateways are simple: they just scan the spectrum and capture LoRa packets. There is no gateway pinning here - devices are not associated with a single gateway; thus, all gateways within range of a device receive the signal. The gateways then forward their data to a network service that handles the packet. +For hardware, you need devices and gateways, similar to how you would set up a Wi-Fi network. Gateways are simple: they scan the spectrum and capture LoRa packets. There is no gateway pinning here. Devices are not associated with a single gateway; thus, all gateways within range of a device receive the signal. The gateways then forward their data to a network service that handles the packet. -The network service deduplicates packets when multiple gateways receive the same packet, decrypts the message (everything is end-to-end encrypted), handles LoRa features such as adaptive data rating and so on. It then forwards the decrypted data to your application. +The network service deduplicates packets when multiple gateways receive the same packet, decrypts the message (everything is end-to-end encrypted) and handles LoRa features, such as adaptive data rating. It then forwards the decrypted data to your application. Often, network service providers allow you to run parts of the network - such as the application server, which decrypts the messages - yourself. -There are five requirements. +You need hardware: -We need hardware: +- Gateways. +- Devices. -* Gateways. -* Devices. +And software: -And we need software: +- Device firmware. +- A network service. +- An app. -* Device firmware. -* A network service. -* An app. +This guide shows you: -This guide shows you which hardware you can buy and two online services you can use to write device firmware and handle your LoRa traffic. +- Which hardware you can buy. +- How to configure a gateway. +- How to write device firmware. +- How to set up a web application to show your LoRa traffic. -### Getting a gateway +**Note:** The frequency that LoRa uses differs among regions. Make sure your gateways and devices are legal in your jurisdiction. For example, use 915 MHz radios in the United States and 868 MHz radios in Europe. You can find more information in the [LoRaWAN regional parameters](http://net868.ru/assets/pdf/LoRaWAN-Regional-Parameters-v1.1rA.PDF) specification. -You have [a lot of choices in the gateways](https://www.loriot.io/gateways.html) you can use, but we've had good experience with these three: +#### 1.1 - Choosing a gateway -* [Kerlink IoT station](http://www.kerlink.fr/en/products/lora-iot-station-2/wirnet-station-868). Expensive (around 1,200 euros) but great build quality and range. -* [MultiTech Conduit](http://www.multitech.com/brands/multiconnect-conduit). About one-third of the price of the Kerlink (about 450 euros) and good for small setups. (Put a bigger antenna on it though.) MultiTech also has a [rugged outdoor](http://www.multitech.com/brands/multiconnect-conduit-ip67) version. -* Building your own with a Raspberry Pi and an [IMST iC880A](http://webshop.imst.de/catalogsearch/result/?q=iC880A) concentrator. At about 230 euros, this is the most cost-efficient option. +You have [many choices in the gateways](https://www.loriot.io/lora-gateways.html) you can use, but we've had good experience with these three: -![Self built gateway using a Raspberry Pi and an IMST iC880A](assets/lora5.jpg)Self-built LoRa gateway based on Raspberry Pi 2 and IMST iC880A. Total cost is about 230 euros. +- [Kerlink Wirnet station](https://www.kerlink.com/product/wirnet-station/). Expensive (around 1,200 euros) but great build quality and range. +- [MultiTech conduit](http://www.multitech.com/brands/multiconnect-conduit). About 1/3 of the price of the Kerlink (about 450 euros) and good for smaller setups. MultiTech also has a [rugged outdoor](http://www.multitech.com/brands/multiconnect-conduit-ip67) version. Make sure you also order the LoRa mCard. +- Building your own with a Raspberry Pi and an [IMST iC880A](http://shop.imst.de/wireless-modules/lora-products/8/ic880a-spi-lorawan-concentrator-868-mhz) concentrator. At about 150 euros, this is a cost-efficient option. -For development purposes, one gateway is enough, but in a production deployment, you need at least two because there will always be dark spots in your network. - -### Getting a device - -You also need to build devices. If you use ARM mbed (and you should), you can either use: - -* A development board with a LoRa transceiver: - * [MultiTech xDot](https://developer.mbed.org/platforms/MTS-xDot-L151CC/). - * The xDot is already FCC/CE certified and shielded, so it's a good choice if you want to build custom hardware. - * [MultiTech mDot](https://developer.mbed.org/platforms/MTS-mDot-F411/) and the [UDK2 board](http://www.digikey.com/product-detail/en/multi-tech-systems-inc/MTUDK2-ST-MDOT/591-1278-ND/5247463). - * As an alternative, you can use the [MultiTech mDot EVB](https://developer.mbed.org/platforms/mdotevb/), which is the mDot reference design. - * Like the xDot, the mDot is already FCC/CE certified and shielded. -* A microcontroller that runs mbed (in this article, we're using the [Nordic nRF51-DK](https://developer.mbed.org/platforms/Nordic-nRF51-DK/), though most microcontrollers work) with a LoRa shield: - * [SX1272MB2xAS](https://developer.mbed.org/components/SX1272MB2xAS/) - shield based on the SX1272 transceiver. - * [SX1276MB1xAS](https://developer.mbed.org/components/SX1276MB1xAS/) - shield based on the SX1276 transceiver. +![Self-built gateway using a Raspberry Pi and an IMST iC880A](assets/lora5.jpg)Self-built LoRa gateway based on Raspberry Pi 2 and IMST iC880A. Total cost is about 150 euros. -This document contains instructions for the MultiTech mDot and the SX1276MB1xAS shield, but the same principles apply to all other combinations. +For development purposes, one gateway is enough, but in a production deployment, you need at least two because there will always be dark spots in your network. -**Note:** When ordering hardware, always make sure you get the variant that works in your region (for example 868 MHz in Europe, 915 MHz in the US). +![Kerlink Wirnet station mounted in Oslo](assets/lora18.jpg)Kerlink Wirnet station overlooking the Oslo fjord. -### Network server +#### 1.2 - Choosing a device -Now on to the software side. You need a server that understands the LoRa protocol and can interpret the data the device sends. It's possible to roll your own (Semtech can give you its reference implementation if you sign an NDA), but there are also companies building LoRa network servers as a service, handling everything on your behalf. This article discusses two such services: the Switzerland-based startup [LORIOT](https://loriot.io), and [IoT-X](http://iot-x.com) from the UK-based Stream Technologies. +You also need to build devices. If you use Mbed OS (and you should), you can either use: -Because a network server only processes your data and doesn't store it, you need a place to store your messages, as well. Both services allow you to hook into their service over a TCP socket, websocket or MQTT client and forward your data to the cloud service of your choice (or straight to your application). +- A development board with a LoRa transceiver: + - [L-Tek FF1705](https://os.mbed.com/platforms/L-TEK-FF1705/). + - [MultiTech xDot](https://os.mbed.com/platforms/MTS-xDot-L151CC/). + - [MultiTech mDot](https://os.mbed.com/platforms/MTS-mDot-F411/) and the [UDK2 board](http://www.digikey.com/product-detail/en/multi-tech-systems-inc/MTUDK2-ST-MDOT/591-1278-ND/5247463). + - [MultiTech mDot EVB](https://os.mbed.com/platforms/mdotevb/). + - [B-L072Z-LRWAN1 LoRa®Discovery kit](https://os.mbed.com/platforms/ST-Discovery-LRWAN1/). +- An Mbed OS 5 Enabled development board together with a LoRa shield: + - [SX1272MB2xAS](https://os.mbed.com/components/SX1272MB2xAS/) - shield based on the SX1272 transceiver. + - [SX1276MB1xAS](https://os.mbed.com/components/SX1276MB1xAS/) - shield based on the SX1276 transceiver. -#### LORIOT +This tutorial applies to all combinations listed above. -LORIOT is free for up to one gateway and up to ten end-devices. The free plan has some limitations: it does not include bidirectional data (sending messages back from the cloud to a device) or over-the-air activation. You can buy these services as an upgrade though (starting at 57 euros per month). +**Note:** When ordering hardware, always make sure you get the variant that works in your region (for example 868 MHz in Europe and 915 MHz in the US). -#### IoT-X +#### 1.3 - Network server -IoT-X is a connectivity management platform from Stream Technologies, which handles both cellular and LoRa connected devices. A [form to request a trial](http://iot-x.com/iotx/) is available on its website. +For software, you need a server that understands the LoRa protocol and can interpret the data the device sends. It's possible to use your own (Semtech can give you its reference implementation if you sign an NDA), but there are also companies building LoRa network servers as a service, handling everything on your behalf. This article uses [The Things Network](https://www.thethingsnetwork.org), an open source, globally distributed network service that also has a free hosted community edition. -## Setting up the gateway +Because a network server only processes your data and doesn't store it, you need a somewhere to store your messages, as well. The Things Network allows you to hook into its service through an MQTT client and forward your data to the cloud service of your choice (or straight to your application). -You now need to configure the gateway by installing software that scans the spectrum and forwards all LoRa packets to the network server. To do this, you will need to log into the gateway. Below are setup instructions for the three gateways suggested earlier. +### 2. Setting up the gateway -**Note:** This section assumes that you're familiar with SSH. +You now need to configure the gateway by installing software to scan the spectrum and forward all LoRa packets to the network server. Below are setup instructions for the three gateways suggested earlier. -### Kerlink IoT station +#### 2.1 - Prerequisites -To configure the Kerlink: +##### Kerlink Wirnet stations -1. Connect the gateway to your network over Ethernet. -1. The gateway gets an IP through DHCP. -1. To quickly find the gateway, look in the DHCP table on your router or use [nmap](http://nmap.org) via `nmap -p 22 192.168.2.*` (if that's your subnet). -1. You can now log into the gateway through SSH with the username `root` and password `root`. +Follow the instructions in [this document](https://www.thethingsnetwork.org/docs/gateways/kerlink/config.html). -### MultiTech Conduit +##### MultiTech Conduit -The Conduit is configured with DHCP disabled, so you need to enable this first. There are two options to do this: either via Ethernet or via micro-USB. +The conduit is configured with DHCP disabled, so you need to enable this first. There are two options to do this: either through Ethernet or through micro-USB. -__Using Ethernet__ +**Using Ethernet** -1. Connect to the Conduit over Ethernet (from the Conduit to your computer). +1. Connect to the conduit over Ethernet (from the conduit to your computer). 1. Set a static IP address of 192.168.2.2 for your computer. 1. Set a static IP address of 192.168.2.1 as your router. 1. Log in through SSH to 192.168.2.1 with the username `root` and password `root`. +**Over micro-USB** -__Over micro-USB__ - -1. Connect to the Conduit using a micro-USB cable. +1. Connect to the conduit using a micro-USB cable. 1. The gateway appears as a serial device. -1. You can use a program such as [GNU screen](https://www.gnu.org/software/screen/) or [PuTTY](http://putty.org) to log into the gateway with the username `root` and password `root`. +1. You can use a program such as [GNU Screen](https://www.gnu.org/software/screen/) or [PuTTY](http://putty.org) to log into the gateway with the username `root` and password `root`. -**Note when logging in fails:** If logging in as `root` fails, but you can log in with the username `admin` and the password `admin`, you are running the AEP firmware. To proceed, update your gateway firmware to mLinux. Instructions are [here](http://www.multitech.net/developer/software/mlinux/using-mlinux/flashing-mlinux-firmware-for-conduit/). +**Note if logging in fails:** If logging in as `root` fails but you can log in with the username `admin` and the password `admin`, you are running the AEP firmware. To proceed, update your gateway firmware to mLinux. Use [these instructions](http://www.multitech.net/developer/software/mlinux/using-mlinux/flashing-mlinux-firmware-for-conduit/). Now that you are connected, you can set up the gateway: -1. Enable DHCP by following Step 4 in [this document](http://www.multitech.net/developer/software/mlinux/getting-started-with-conduit-mlinux/). +1. Enable DHCP by following Step 4 in [this document](http://www.multitech.net/developer/software/mlinux/getting-started-with-conduit-mlinux/). 1. Connect the gateway over Ethernet to your router. -1. Follow the steps under [Kerlink IoT station above](#kerlink-iot-station) to find the IP address and log in over SSH. +1. Verify that the gateway is connected to the internet (for example, by running `ping 8.8.4.4`). + +##### Raspberry Pi + +Follow the instructions in [this document](https://github.com/ttn-zh/ic880a-gateway/wiki). + +#### 2.2 - Registering the gateway + +1. [Sign up](https://console.thethingsnetwork.org) for an account at The Things Network. +1. You're redirected to the dashboard page. +1. Click **Gateways**. + + ![Gateways](assets/ttn1.png) + +1. Click **Register gateway**. + + ![Add a new gateway](assets/ttn2.png) + +1. Fill in the details of your gateway. + + ![Gateway details](assets/ttn3.png)Gateway details: The Things Network uses the gateway location to create coverage maps, so make sure the location is set correctly. + +1. If you use the Kerlink Wirnet station: + - Tick **I'm using the legacy packet forwarder**. + - Under **Gateway EUI**, enter the EUI of the gateway (printed on the box). + +1. If you use the Raspberry Pi: + - Tick **I'm using the legacy packet forwarder**. + - Under **Gateway EUI**, enter the EUI that printed when you called `install.sh` in step 2.1. + +1. Click **Register gateway**. +1. You have created the gateway. + +If you use the MultiTech conduit, you need the 'Gateway key' to authenticate the gateway to the network. Copy it. + +![Gateway key is required for authentication to the network](assets/ttn4.png) + +#### 2.3 - Installing the packet forwarder + +##### Kerlink Wirnet station or Raspberry Pi + +No further action required. The gateway shows as 'Connected' in the TTN console. + +![Connected!](assets/ttn7.png)Connected! + +##### MultiTech conduit + +1. On the gateway, run: + + ``` + $ wget https://github.com/kersing/multitech-installer/raw/master/installer.sh + $ sh installer.sh + ``` + +1. A wizard starts. Answer the questions. + + ![Configuring the MultiTech Conduit gateway for The Things Network](assets/ttn5.png)Wizard for configuring the MultiTech Conduit. + +1. After the gateway reboots, log back in. +1. Then run (again): + + ``` + $ sh installer.sh + ``` + +1. Fill in the remaining questions. + + ![Configuring the MultiTech Conduit gateway for The Things Network (step 2)](assets/ttn6.png)Wizard (2) for configuring the MultiTech Conduit. + +1. After this, the gateway shows as **Connected** in the TTN console. + + ![Connected!](assets/ttn7.png)Connected! + +### 3. Building a device + +This section explains how to build a device that can send sensor data over the LoRa network. For example, you can create a motion sensor using a [PIR sensor](https://www.adafruit.com/products/189) (less than 10 euros). Of course, you can use any other sensor. + +![nRF51-DK, LoRa shield and a PIR sensor](assets/lora6.jpg)PIR sensor hooked up to a Nordic Semiconductor nRF51-DK with a SX1276 LoRa shield + +#### 3.1 - Some notes on writing firmware + +##### Restrictions on sending data + +You cannot send data constantly because of spectrum regulations. Although the spectrum that LoRa uses is unlicensed, it is regulated. For example, in Europe, there are duty cycle limitations of 1% - meaning you can only send 1% of the time. In the US, there's dwell time, which requires you to wait at least 400 ms between transmissions. If you violate these regulations, your data transmission fails. How fast you are allowed to send data depends on the spread factor you use. With a higher spread factor, it takes longer to send a message - though the chance that a gateway receives it increases. However, you need to wait longer before you can send data again. During development, you can set the spread factor to SF7 (the lowest), so you can send every 6-7 seconds. + +LoRaWAN has a feature called Adaptive Data Rating (ADR), through which the network can control the spread factor. You probably want this enabled. + +##### Blocked pins + +A disadvantage of the SX1272 and SX1276 LoRa shields is that they block a lot of pins. You can solder new headers on the back of the shield to add new peripherals, or use a microcontroller such as the nRF51-DK or a NUCLEO board that has more pins available than just the Arduino headers. + +#### 3.2 - Registering the device on The Things Network + +LoRaWAN uses an end-to-end encryption scheme that uses two session keys. The network server holds one key, and the application server holds the other. (In this tutorial, TTN fulfils both roles). These session keys are created when the device joins the network. For the initial authentication with the network, the application needs its device EUI, the EUI of the application it wants to join (referred to as the application EUI) and a preshared key (the application key). + +The device EUI and application EUI are globally unique identifiers. You can buy a block of EUIs from the [IEEE](http://standards.ieee.org/develop/regauth/tut/eui.pdf). Modules often already come with an EUI, which is printed on the device. If you're using a radio shield you can use an EUI from The Things Network's block. + +**Note:** In LoRaWAN 1.1, the join key replaces the application key, and the join server handles the initial authentication. However, at the time of writing, this is not implemented on The Things Network. + +Register the device in The Things Network, and generate some keys: + +1. Go to [The Things Network console](https://console.thethingsnetwork.org). +1. Click **Applications**. +1. Click **Add application**. + + ![Add application in TTN](assets/ttn8.png) + +1. Fill in the details of your application, and click **Add application**. + + ![Application details](assets/ttn9.png)Filling in the application details in The Things Network. + +1. You're redirected to the application page. Under **Devices**, click **Register device**. + + ![Register device](assets/ttn10.png) + +1. If your device has an EUI printed on it, enter this in **Device EUI**. + + ![Device EUI on a LoRa module](assets/ttn11.png)The device EUI is often printed on the module or on the box. -### Raspberry Pi and IMST iC880A +1. If your device does not have an EUI printed on it, press the **generate** button to allocate an EUI from a block owned by The Things Network. Do **not** make an EUI up; it must be globally unique. -First, make sure that the Raspberry Pi is connected to the internet and that you connected the IMST iC880A over USB. (If you have the SPI version, look at the [IMST website](http://www.wireless-solutions.de/products/radiomodules/ic880a)). + ![Generating Device EUI](assets/ttn12.png) -Log into the Pi over SSH, and follow Steps 3.1 - 3.5 in [this document](http://www.wireless-solutions.de/images/stories/downloads/Radio%20Modules/iC880A/iC880A_QuickStartGuide.pdf). +1. Fill in the rest of the details, and click **Register**. -**Note:** Use [lora_gateway 2.0.0](https://github.com/Lora-net/lora_gateway/releases/tag/v2.0.0), not the latest version. (Run `git checkout v2.0.0` in the lora_gateway folder). + ![Registering a new device in TTN](assets/ttn13.png) -After following these steps: +1. The device page opens. It contains the keys that your device uses when authenticating with the network. Click the `<>` button to get the keys as a byte array. This makes it easy to copy the keys into code. -1. Restart the Pi. + ![Showing device keys in TTN](assets/ttn14.png) + +Now that the device is registered in The Things Network, you can start writing code! + +#### 3.3 - Importing the demo application + +Mbed comes with the Arm Mbed Online Compiler, which you can use to build applications without needing to install anything on your computer. (Mbed also has [offline tools](https://os.mbed.com/docs/latest/tools/index.html)). + +1. [Sign up](https://os.mbed.com/account/signup/?next=%2F) for an account on Arm Mbed, which hosts the Online Compiler. +1. Find your development board on [the platforms page](https://os.mbed.com/platforms/). +1. Click **Add to your Mbed Compiler**. +1. Go to [mbed-os-example-lorawan](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/). +1. Click **Import this program**. +1. You're redirected to the Online Compiler, where you can give the program a name. + + ![Importing a program to get started](assets/lora7.png)Importing a program to get started + +**Note:** Make sure you select the correct board in the top right corner of the compiler. + +![Selecting the right board](assets/lora8.png)Selecting the correct board + +#### 3.4 - Setting keys + +In the Online Compiler: + +1. Open `mbed_app.json`. This file contains the configuration for the application and holds the authentication keys. +1. If you have a SX1272 or SX1276 **shield** (not if you have a module), set your radio type under `lora-radio`. +1. Under `lora.device-eui`, enter the device EUI from the TTN console. +1. Under `lora.application-eui`, enter the application EUI from the TTN console. +1. Under `lora.application-key`, enter the application key from the TTN console. + + ![Putting the LoRaWAN authentication keys in mbed_app.json](assets/ttn15.png)Correct keys set in `mbed_app.json` + +1. Under `lora.phy` specify the channel plan for your region. A list of possible values is listed under '[Selecting a PHY'](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan#selecting-a-phy) in the docs. + +##### Sending the value of the PIR sensor + +To send the current value of the PIR sensor (whether it sees movement), in the Online Compiler: + +1. Open `main.cpp`. +1. Replace the function `send_message()` with: + + ```cpp + static void send_message() { + static InterruptIn pir(D5); // If you hooked the sensor up to a different pin, change it here + + // create a one-byte payload which contains whether the PIR sensor is *high* or *low* + uint8_t buffer[] = { pir.read() }; + int16_t retcode = lorawan.send(LORAWAN_APP_PORT, buffer, sizeof(buffer), MSG_CONFIRMED_FLAG); + + if (retcode == 0) { + printf("Sent message over LoRaWAN successfully!\n"); + } + else { + printf("Failed to send message (duty-cycle violation?) (%d)\n", retcode); + } + } + ``` + +#### 3.5 - Verifying the setup + +Now you can verify whether the setup works by flashing this application to your board. + +1. In the Online Compiler, click the **Compile** button. + + ![Compile button](assets/lora10.png)Compile button + +1. When compilation succeeds, the compiler sends a file to your computer. +1. Plug your development board into the computer (over micro-USB) to mount it as a USB mass storage device. In most cases, you do not need a driver, but you can find drivers [here](https://os.mbed.com/docs/latest/tutorials/windows-serial-driver.html). +1. Once the device mounts, drag the compiled file onto the board. This causes the device to boot. You can then see the device joining and then sending messages in the The Things Network console, under the **Data** tab: + + ![Data](assets/ttn19.png)We've got data! + +**Note 1:** You can hook a [serial monitor](https://os.mbed.com/docs/latest/tutorials/serial-comm.html) up to the development board (baud rate 115,200) to see debugging messages. + +**Note 2:** No data in the **Data** tab? Verify that the gateway can receive messages. In the TTN console, go to your gateway, and see if any data comes through under the **Traffic** tab. If you see your device there but not under the device page, the keys are probably wrong. + +##### Sending manually + +By default, the application sends data automatically. If you want to change this, remove this line from `main.cpp`: + +```cpp +ev_queue.call_every(TX_TIMER, send_message); +``` + +Call `send_message` whenever you want (for example after the state of the sensor changes). Note that you still need to adhere to the duty cycle, so you may not be able to send data immediately. + +#### 3.6 - Relaying data back to the device + +You can also send data back to the device. Because LoRaWAN (in Class-A mode, which you're using here) is not continuously connected to the network, you need to wait for a receive (RX) window to occur to receive data. An RX window opens after a transmission. So you need to *send* to the network before you can receive a message. If you send a message from The Things Network to your device, the network automatically queues the message and delivers it in the next RX window. + +You can toggle the LED on your development board over LoRa. In the Online Compiler: + +1. Open `main.cpp`. +1. Replace the `receive_message` function with: + + ```cpp + static void receive_message() { + static DigitalOut led(LED1, 0); // the LED under control, default value of 0 + + int16_t retcode = lorawan.receive(LORAWAN_APP_PORT, rx_buffer, + LORAMAC_PHY_MAXPAYLOAD, + MSG_CONFIRMED_FLAG|MSG_UNCONFIRMED_FLAG); + + // ignore errors while retrieving + if (retcode < 0) return; + + led = rx_buffer[0]; // set the value of the LED depending on the first byte in the message + + printf("Received %d bytes: ", retcode); + for (uint8_t i = 0; i < retcode; i++) { + printf("%x", rx_buffer[i]); + } + printf("\n"); + } + ``` + + **Note:** On some development boards, writing `0` to the LED turns them on. On others, writing `1` does this. It depends on the wiring of the board. + +1. Compile, and flash the application. +1. When the device is back online, use the The Things Network console to queue a message. Go to your device page, and under **Downlink**, select port **21** and data `01`. Then press **Send**. + + ![Queuing a downlink message using the TTN console](assets/ttn16.png)Queuing a downlink message over port 21 + +1. After the next transmission, the LED toggles, and a message appears on the serial console. Try the same thing now by sending `0`. + +### 4. Getting your data out of the The Things Network + +The system works and sends data in two directions, but the data is not stored anywhere. You can change that. The Things Network offers a data API to get the data out of the network. You can then store it on your own servers or forward it to a cloud service. + +For this tutorial, we built a small web application that listens for events from the movement sensors and shows an overview of all sensors. To use this application, you need a recent version of [Node.js](https://nodejs.org) installed on your computer. + +![Application that shows movement information, built using Mbed OS and The Things Network](assets/lora19.png)Demo application + +To build this application, first grab an access key from The Things Network: + +1. Go to your application in the TTN console. +1. Locate your **Application ID**, and make note of it. + + ![TTN Application ID](assets/ttn17.png) + +1. Locate your **Access Key**, click the **show** button and make note of it, as well. + + ![TTN Access Key](assets/ttn18.png) + +Now clone, the demo application, and run it. + +1. [Download the demo application](https://github.com/ARMmbed/lora-docs/archive/master.zip), and extract it. +1. In the unzipped application, locate `ttn-node-app/server.js`, and paste your Application ID and Access Key on lines 1 and 2. +1. Open a terminal - or command prompt - and navigate to the folder where you unzipped the application. 1. Run: - ``~/LoRa/lora_gateway/lora_gateway/util_pkt_logger/util_pkt_logger`` + ``` + $ cd ttn-node-app + $ npm install + $ node server.js + ``` + + This shows: + + ``` + Connecting to the The Things Network data channel... + Connected to The Things Network data channel + Retrieving devices... + Retrieved devices (2) + Web server listening on port 5270! + ``` + +1. Now, open a web browser, and navigate to http://localhost:5270 to see the application running. -1. You see 'INFO: concentrator started, packet can now be received', which indicates that everything is functioning. +### 5. Recap -## Setting up the network server +LoRa/LoRaWAN is a technology with which anyone can set up a network and start building long-range IoT devices with a relatively small investment. We hope this guide helped you get started, and we would love to see what you build with LoRa and Mbed. -Now that you have set up the gateways and they can reach the internet, it's time to install the network service software on them, so they have a place to send the LoRa packets. +#### More material -* [Continue setting up your network with LORIOT](loriot.md). -* [Continue setting up your network with IoT-X](iotx.md). \ No newline at end of file +- [Webinar: getting started with LoRa using Arm Mbed and The Things Network](https://pages.arm.com/2017-10-29-webinar-registration.html). +- [Mbed OS LoRaWAN stack documentation](https://os.mbed.com/docs/latest/reference/lorawan.html). +- [Firmware updates over LoRaWAN](https://os.mbed.com/blog/entry/firmware-updates-over-lpwan-lora/). +- [Presentations from The Things Conference](https://www.youtube.com/playlist?list=PLM8eOeiKY7JUhIyxWWU2-qziejDbBg-pf). diff --git a/docs/iotx.md b/docs/iotx.md deleted file mode 100644 index bfe17cd..0000000 --- a/docs/iotx.md +++ /dev/null @@ -1,406 +0,0 @@ -# Setting up your LoRa network on IoT-X - -If you haven't done so, please read [Building your own private LoRa network](intro-to-lora.md) first. - -Now that you have set up the gateways and they can reach the internet, it's time to install and configure the LoRa packet forwarder on them, so they have a place to send the LoRa packets. - -## Installing the LoRa packet forwarder - -The [LoRa packet forwarder](https://github.com/Lora-net/packet_forwarder) is an open-source application that runs on a gateway and forwards captured LoRa packets to a host of your choice. You can install the packet forwarder and configure it to send its data to IoT-X. - -To install the packet forwarder, follow these instructions: - -### Kerlink IoT station - -The Kerlink IoT station comes with the packet forwarder installed. Run `ps | grep pkt` to verify whether it's already running. You can find the location of the packet forwarder via `find / -name global_conf.json`. - -### MultiTech Conduit - -Follow the steps in [this document](https://www.multitech.net/developer/software/lora/conduit-mlinux-convert-to-basic-packet-forwarder/). - -### Raspberry Pi and IMST iC880A - -1. Clone the [Lora-net/packet_forwarder](https://github.com/Lora-net/packet_forwarder) repository. -1. Check out [v2.2.1](https://github.com/Lora-net/packet_forwarder/commit/28df8c0655bbf6d5d5b62d4e8e56c0c2e427558e) tag - `git checkout v2.2.1`. -1. In the 'basic_pkt_fwd' folder, run `make` to build the packet forwarder. - -## Configuring the LoRa packet forwarder - -Next you need a configuration file for the packet forwarder, which you can retrieve from the IoT-X website. - -1. [Log in](https://stream.iot-x.com/login) to your account. -1. You're redirected to the dashboard page. -1. In the left sidebar, click *Lora > Gateways*. -1. Click *Add Gateway* to register a new gateway. - - ![First step to registering a new gateway](assets/stream1.png)First step to registering a new gateway - -1. You're taken through a wizard. Follow the steps. -1. You're taken to the gateway page, which has the configuration file for your platform. Click *Download Config* to download the configuration file. - - ![Downloading the configuration file...](assets/stream2.png)The configuration file - -1. On the gateway, in the packet forwarder directory, find the `global_conf.json` file, and replace it with the download config. -1. (Re)start the packet forwarder. -1. The gateway shows as connected on the IoT-X gateway page, and you're ready to work on the device. - - ![Connected!](assets/stream3.png)Connected! - -## Building a device - -Now to the interesting work: building a device that can send sensor data over the LoRa network. For example, you can create a simple motion sensor using a [PIR sensor](https://www.adafruit.com/products/189) (under 10 euros at your local hardware store, and 2 euros when ordering from China). Of course, you can use any other sensor. - -![nRF51-DK, LoRa shield and a PIR sensor!](assets/lora6.jpg)PIR sensor hooked up to a Nordic Semiconductor nRF51-DK with a LoRa shield - -### Some notes on writing firmware - -#### Sending data constantly - -You cannot send data constantly because of duty cycle limitations. This is a requirement of using the open spectrum. If you send too quickly, sending will fail. How fast you are allowed to send depends on the spread factor that you use. With a higher spread factor, it takes longer to send a message - though the chance that it will be received by a gateway increases. Thus, you need to wait longer before you can send again. During development, you can set the spread factor to SF7 (the lowest), so you can send every 6-7 seconds. - -LoRaWAN has a feature called Adaptive Data Rating (ADR), through which the network can control the spread factor. You probably want this enabled. - -#### Blocking pins - -A disadvantage of the LoRa shield is that it blocks all the pins. You can solder some new headers on the back of the shield to add new peripherals, or use a microcontroller like the nRF51-DK that has the pins available twice, once through hole connectors and once through female headers. - -### Registering the device on IoT-X - -LoRa is end-to-end encrypted, with two sets of keys. You'll need to program these keys and a device ID into the device firmware. You'll use these keys to sign your messages and be verified by the network server. - -To generate a new key pair: - -1. Go to the IoT-X dashboard. -1. Click *Applications*. -1. If you do not have an application yet, click *Create an application*, and fill in the form. -1. Click on application name to go to the application overview. - - ![Application overview](assets/stream4.png)Application overview - -1. In the **Add a device** form, under **Device Type** choose **OTA**. -1. In the **Add a device** form, under **Device EUI**: - * If your device has a sticker that says **EUI** (all MultiTech devices), enter this EUI. - * If your device does not have a sticker (all shields), [generate an 8-byte random number](https://www.random.org/cgi-bin/randbyte?nbytes=8&format=h), and enter this value without spaces. -1. In the **Add a device** form, under **Device EUI**, enter [a 16-byte random number](https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h) without spaces. -1. In the **Add a device** form, under **Activate this Device**, enable the checkbox. -1. Click *Add*. - - ![Adding a device](assets/stream5.png)Adding a device - -1. Choose a tariff, and click *Activate*. - - ![Activating a device](assets/stream6.png)Activating a device - -1. The device is activated. Click on *LoRa > Applications > Your application name* to go back to the application overview. -1. Click on the device that you just created, and write down the **App EUI** and **App Key**. - -Now that you have the keys, you can start writing software. - -### Using the LoRa shield - - -#### Importing the boilerplate program into the online IDE - -1. [Sign up](https://developer.mbed.org/account/signup/?next=%2F) for an account on ARM mbed, which hosts the Online Compiler you'll use. -1. Find your microcontroller on [the Platforms page](https://developer.mbed.org/platforms/). -1. Click *Add to your mbed compiler*. -1. Go to [LoRaWAN-lmic-app](https://developer.mbed.org/teams/Semtech/code/LoRaWAN-lmic-app/). -1. Click *Import this program*. -1. You're redirected to the Online Compiler, where you can give the program a name. - - - ![Importing a program to get started](assets/lora7.png)Importing a program to get started - -**Note:** Make sure that you select the correct board in the top right corner of the Online Compiler. - -![Selecting the right board](assets/lora8.png)Selecting the correct board - - -#### Setting shield frequency - -You need to set the correct frequency for the version of the shield you have (and where you are in the world). - -Open ``LMiC/lmic.h``, and find the following lines: - -```cpp -// mbed compiler options -//#define CFG_eu868 1 -#define CFG_us915 1 -``` - -Make sure the correct line is uncommented, depending on the shield version that you have. - -__If you have the SX1276MB1LAS:__ - -```cpp -//#define CFG_eu868 1 -#define CFG_us915 1 -``` - -__If you have the SX1276MB1MAS:__ - -```cpp -#define CFG_eu868 1 -//#define CFG_us915 1 -``` - -#### Adding IoT-X keys - -Now, program the keys from IoT-X into the device firmware. You'll need keys from both the **Application** page and the **Device** page. - -![IoT-X application page](assets/stream8.png)IoT-X application page - -![IoT-X device page](assets/stream7.png)IoT-X device page - -Open `main.cpp`, and set `OVER_THE_AIR_ACTIVATION` to `1`: - -```cpp -#define OVER_THE_AIR_ACTIVATION 1 -``` - -Then, change the following lines: - -```cpp -// application router ID (LSBF) -static const uint8_t AppEui[8] = -{ - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 -}; - -// unique device ID (LSBF) -static const u1_t DevEui[8] = -{ - 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF -}; - -// device-specific AES key (derived from device EUI) -static const uint8_t DevKey[16] = -{ - 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6, - 0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C -}; -``` - -* Set `AppEui` to the application's **Unique Identifier** (purple box). -* Set `DevEui` to the device's **Device EUI** (green box). -* Set `DevKey` to the device's **App Key** (red box). - -**Note:** Turn them into hex numbers. For example, a key of `5ADA30AA` should be `0x5A, 0xDA, 0x30, 0xAA` in your code. - - -#### Verifying the setup - -Now you can verify whether the setup works by clicking the *Compile* button. - -![Compile button](assets/lora10.png)Compile button - -When compilation succeeds, a file is downloaded. - -Plug your development board into the computer (over micro-USB) to mount it as a USB mass storage device. In most cases, you don't need a driver, but you can find drivers [here](https://docs.mbed.com/docs/debugging-on-mbed/en/latest/Debugging/printf/) just in case. - -Once the device mounts, drag the compiled file onto the board. This causes the device to boot up. You can then see messages coming in to the IoT-X application page: - -![We've got data!](assets/stream9.png)We've got data! - -#### Switching to manual sending - -By default, the application sends data automatically. If you want to change this, remove these lines from ``main.cpp``: - -```cpp -if( txOn == true ) -{ - //Sends frame every APP_TX_DUTYCYCLE +/- APP_TX_DUTYCYCLE_RND random time (if not duty cycle limited) - os_setTimedCallback( &sendFrameJob, - os_getTime( ) + ms2osticks( APP_TX_DUTYCYCLE + randr( -APP_TX_DUTYCYCLE_RND, APP_TX_DUTYCYCLE_RND ) ), - onSendFrame ); - - ////Sends frame as soon as possible (duty cycle limitations) - //onSendFrame( NULL ); -} -``` - -You can now add code that sends a message whenever you want it to, for example when an interrupt fires because someone moves in front of your PIR sensor. For example: - -```cpp -InterruptIn pir(D5); - -static void prepareTxFrame( void ) -{ - LMIC.frame[0] = pir; // current state of the pir sensor -#if ( LORAWAN_CONFIRMED_MSG_ON == 1 ) - LMIC.frame[1] = LMIC.seqnoDn >> 8; - LMIC.frame[2] = LMIC.seqnoDn; - LMIC.frame[3] = LMIC.rssi >> 8; - LMIC.frame[4] = LMIC.rssi; - LMIC.frame[5] = LMIC.snr; -#endif -} - -void movement() { - onSendFrame(NULL); -} - -void no_movement() { - onSendFrame(NULL); -} - -int main( void ) { - - pir.rise(movement); - pir.fall(no_movement); - - // ... lora related things -} -``` - -Change the content of the `prepareTxFrame` function to change which data you're sending (also update `LORAWAN_APP_DATA_SIZE`). Now you'll get a message whenever the PIR sensor changes state (from motion to no-motion and the other way around). - -### Using the MultiTech mDot - - -#### Importing the boilerplate program into the online IDE - -1. [Sign up](https://developer.mbed.org/account/signup/?next=%2F) for an account on ARM mbed, which hosts the Online Compiler you'll use. -1. Go to the [MultiTech mDot platform page](https://developer.mbed.org/platforms/MTS-mDot-F411/). -1. Click *Add to your mbed compiler*. -1. Go to the [Dot-Examples](https://developer.mbed.org/teams/MultiTech/code/Dot-Examples/) project page. -1. Click *Import this program*. -1. You're redirected to the Online Compiler, where you can give the program a name. - - ![Importing a program to get started](assets/stream10.png)Importing a program to get started - -1. After importing, right click on your application, and choose *Import Library > From URL*. - - ![Importing a library](assets/stream11.png)Importing a library - -1. In the modal, under **Source URL**, enter: `https://developer.mbed.org/teams/MultiTech/code/libmDot-mbed5/` and click *Import*. - - ![Adding the libmDot library](assets/stream12.png)Adding the libmDot library - -**Note:** Make sure that you select the correct board in the top right corner of the compiler. - -![Selecting the right board](assets/lora13.png)Selecting the correct board - -#### Adding IoT-X keys - -Now , program the keys from IoT-X into the device firmware. You'll need keys from both the **Application** page and the **Device** page. - -![IoT-X application page](assets/stream8.png)IoT-X application page - -![IoT-X device page](assets/stream7.png)IoT-X device page - -Open `examples\src\ota_example.cpp.cpp`, and change the following code: - -```cpp -static uint8_t network_id[] = { 0x6C, 0x4E, 0xEF, 0x66, 0xF4, 0x79, 0x86, 0xA6 }; -static uint8_t network_key[] = { 0x1F, 0x33, 0xA1, 0x70, 0xA5, 0xF1, 0xFD, 0xA0, 0xAB, 0x69, 0x7A, 0xAE, 0x2B, 0x95, 0x91, 0x6B }; -static uint8_t frequency_sub_band = 0; -static bool public_network = false; -``` - -* Set `network_id` to the application's **Unique Identifier** (purple box). -* Set `network_key` to the device's **App Key** (red box). -* Set `public_network` to `true`. - -**Note:** Turn them into hex numbers. For example, a key of `5ADA30AA` should be `0x5A, 0xDA, 0x30, 0xAA` in your code. - -In addition, change: - -```cpp - update_ota_config_name_phrase(network_name, network_passphrase, frequency_sub_band, public_network, ack); - // update_ota_config_id_key(network_id, network_key, frequency_sub_band, public_network, ack); -``` - -into: - -```cpp - // update_ota_config_name_phrase(network_name, network_passphrase, frequency_sub_band, public_network, ack); - update_ota_config_id_key(network_id, network_key, frequency_sub_band, public_network, ack); -``` - -#### Verifying the setup - -Now you can verify whether the setup works by clicking the *Compile* button. - -![Compile button](assets/lora10.png)Compile button - -When compilation succeeds, a file is downloaded. - -Plug your development board into the computer (over micro-USB) to mount it as a USB mass storage device. In most cases, you don't need a driver, but you can find drivers [here](https://docs.mbed.com/docs/debugging-on-mbed/en/latest/Debugging/printf/) just in case. - -Once the device mounts, drag the compiled file onto the board. This causes the device to boot up. You can then see messages coming in to the IoT-X application page: - -![We've got data!](assets/stream9.png)We've got data! - -#### Switching to manual sending - -By default, the application sends data automatically. If you want to change this, you can change the `sleep_wake_rtc_or_interrupt();` call, and replace it with `sleep_wake_interrupt_only();`. Then sending only happens when you pull the wake-up pin high. - -## Consuming the data over MQTT - -Now that the first three parts of ther network are working, it's time to use the sensor data in a small application. To retrieve data out of the IoT-X network, they offer an MQTT server. MQTT is a well-supported, lightweight messaging protocol, and most programming languages offer a MQTT client library. You can write a node.js application that tells you when movement is detected. Do this by checking the first byte of the LoRa payload (1=movement, 0=no movement). - -### Creating an MQTT user - -1. In IoT-X: go to *Services > MQTT Users*. -1. Click *Add Company*. -1. Create a username and a password - you'll use these credentials to authenticate over MQTT. - - ![Adding a new MQTT user](assets/stream13.png)Adding a new MQTT user - - -### Creating a node.js application - -You can now use any MQTT client to connect to the IoT-X MQTT server. Here is an example in node.js. - -1. Install [node.js](https://nodejs.org/en/). -1. Open a terminal or command window, and create a new folder. -1. In this folder, run `npm install mqtt`. -1. Create a new file `iotx.js`, and add the following content: - - ```cpp - var mqtt = require('mqtt'); - - var client = mqtt.connect('mqtts://lora-eu.iot-x.com', { - username: 'YOUR_USERNAME', - password: 'YOUR_PASSWORD' - }); - - client.on('connect', function () { - console.log('Connected to Stream MQTT'); - client.subscribe('/lora/+/message'); - }); - - client.on('message', function (topic, message) { - var deveui = (topic.split('/').filter(f=>!!f)[1]).toUpperCase(); - - message = JSON.parse(message); - - if (!message.gateway_info) { - /* downlink */ - return; - } - - var buffer = [].slice.call(Buffer.from(message.data, 'base64')); - if (buffer[0] === 1) { - console.log('Movement detected (' + deveui + ')'); - } - else { - console.log('No movement detected (' + deveui + ')'); - } - }); - - client.on('error', err => console.error('Stream MQTT error...', err)); - ``` - - **Note:** Replace `YOUR_USERNAME` and `YOUR_PASSWORD` with the MQTT credentials you created in the previous section. - -1. From the terminal, run `node iotx.js`. - -You now have a fully functioning LoRa network with a device, a gateway and an application. - -![Output from IoT-X over MQTT](assets/stream14.png)Output from IoT-X over MQTT - -## Conclusion - -LoRa is a great technology with a lot of potential, especially because anyone can set up a network and start building long-range IoT devices with a relatively small investment. We hope this guide helped you get started, and we would love to see what you build with LoRa and ARM mbed! \ No newline at end of file diff --git a/docs/loriot.md b/docs/loriot.md deleted file mode 100644 index 349450e..0000000 --- a/docs/loriot.md +++ /dev/null @@ -1,336 +0,0 @@ -# Setting up your LoRa network on LORIOT - -If you haven't done so, please read [Building your own private LoRa network](intro-to-lora.md) first. - -Now that you have set up the gateways and they can reach the internet, it's time to install the LORIOT software on them, so they have a place to send the LoRa packets. - -**Note on the Kerlink IoT station:** Often, the Kerlink IoT station comes preconfigured with the packet forwarder (run `ps | grep pkt` to see if one is running). If this is the case, make sure the packet forwarder does not start on startup by removing the entry from `/etc/init.d`. - -## Installing the LORIOT software - -1. [Sign up](https://eu1.loriot.io/register.html) for an account. -1. You're redirected to the dashboard page. -1. Click the link to register a new gateway. - - ![First step to registering a new gateway](assets/lora2.png)First step to registering a new gateway - -1. You're taken through a wizard. Choose the gateway you have, and follow the steps. -1. You're taken to the gateway page where you'll find the LORIOT binary for your platform and a link to set up documentation. - - ![Almost there...](assets/lora3.png)Almost there... - - **Tip:** Use a tool like scp to copy the binary from your computer to the gateway. For example:
``scp ~/Downloads/loriot_pi_2_iC880A_USB_1.0.1.tar pi@192.168.2.7:~/`` - -1. On the gateway, run the LORIOT binary. -1. The gateway shows as connected on the LORIOT gateway page. You're ready to work on the device. - - ![Connected!](assets/lora4.png)Connected! - -**Tip:** LORIOT has a 'Gateway Tap', which you can access from your gateway page. This allows you to see what messages the gateway is picking up, which is useful when debugging. - -### Automatically starting the LORIOT binary when the gateway starts - -#### Kerlink IoT station - -If you followed the installation steps in the LORIOT documentation, the binary automatically starts whenever the gateway boots. - -#### MultiTech Conduit - -1. Log in over SSH or via the serial port. -1. Create a new file `/etc/init.d/start-loriot.sh`. -1. Edit this file (via `nano /etc/init.d/start-loriot.sh`), and add the following content: - - ``cd /home/root/ && ./loriot_multitech_conduit_mCard_USB_1.0.1`` - - * If you extracted the LORIOT binary somewhere else, edit the path. - * CD into the folder first; otherwise, LORIOT cannot find its certificate. - -1. Make the file executable: `chmod +x /etc/init.d/start-loriot.sh` -1. Link the script: `ln -s /etc/init.d/start-loriot.sh /etc/rc5.d/S99start-loriot.sh` -1. Now, reboot the gateway, and verify that the LORIOT binary is running (via `ps aux | grep loriot`). - -#### Raspberry Pi and IMST iC880A - -Follow the steps on [this page](http://raspberrypi.stackexchange.com/questions/8734/execute-script-on-start-up) to start the LORIOT binary when the Raspberry Pi starts up. - -## Building a device - -Now to the interesting work: building a device that can send sensor data over the LoRa network. For example, you can create a motion sensor using a [PIR sensor](https://www.adafruit.com/products/189) (less than 10 euros at your local hardware store and 2 euros when ordering from China). Of course, you can use any other sensor. - -![nRF51-DK, LoRa shield and a PIR sensor!](assets/lora6.jpg)PIR sensor hooked up to a Nordic Semiconductor nRF51-DK with a LoRa shield - -### Some notes on writing firmware - -#### Sending data constantly - -You cannot send data constantly because of duty cycle limitations. This is a requirement of using the open spectrum. If you send too quickly, sending will fail. How fast you are allowed to send depends on the spread factor that you use. With a higher spread factor, it takes longer to send a message - though the chance that it will be received by a gateway increases. Thus, you need to wait longer before you can send again. During development, you can set the spread factor to SF7 (the lowest), so you can send every 6-7 seconds. - -LoRaWAN has a feature called Adaptive Data Rating (ADR), through which the network can control the spread factor. You probably want this enabled. - -#### Blocking pins - -A disadvantage of the LoRa shield is that it blocks all the pins. You can solder some new headers on the back of the shield to add new peripherals, or use a microcontroller like the nRF51-DK that has the pins available twice, once through hole connectors and once through female headers. - -### Registering the device on LORIOT - -LoRa is end-to-end encrypted, with two sets of keys. You'll need to program these keys and a device ID into the device firmware. You'll use these keys to sign messages and be verified by the network server. - -To generate a new key pair: - -1. Go to the LORIOT dashboard. -1. Click *Applications > Sample App > Manage Devices > Generate New Device*. -1. A device is added to the list. -1. Click the device to go to the device page. -1. At the bottom of the page, find *Seqno checking*, and change this setting to *Relax*. (Call `setRelax()` from the JS console if the button does not show up). - -![Disabling strict sequence number checking](assets/lora9.png)Disabling strict sequence number checking - -Now that you have the keys, you can start writing software. - -### Using the LoRa shield - - -#### Importing the boilerplate program into the online IDE - -1. [Sign up](https://developer.mbed.org/account/signup/?next=%2F) for an account on ARM mbed, which hosts the Online Compiler you'll be using. -1. Find your microcontroller on [the Platforms page](https://developer.mbed.org/platforms/). -1. Click *Add to your mbed compiler*. -1. Go to [LoRaWAN-lmic-app](https://developer.mbed.org/teams/Semtech/code/LoRaWAN-lmic-app/). -1. Click *Import this program*. -1. You're redirected to the Online Compiler, where you can give the program a name. - - - ![Importing a program to get started](assets/lora7.png)Importing a program to get started - -**Note:** Make sure that you select the correct board in the top right corner of the compiler. - -![Selecting the right board](assets/lora8.png)Selecting the correct board - - -#### Setting shield frequency - -You need to set the correct frequency for the version of the shield you have (and where you are in the world). - -Open ``LMiC/lmic.h``, and find the following lines: - -```cpp -// mbed compiler options -//#define CFG_eu868 1 -#define CFG_us915 1 -``` - -Make sure the correct line is uncommented, depending on the shield version that you have. - -__If you have the SX1276MB1LAS:__ - -```cpp -//#define CFG_eu868 1 -#define CFG_us915 1 -``` - -__If you have the SX1276MB1MAS:__ - -```cpp -#define CFG_eu868 1 -//#define CFG_us915 1 -``` - -#### Adding LORIOT keys - -Program the keys from LORIOT into the device firmware. - -![Copying the address and the keys from LORIOT into the device firmware](assets/lora17.png)Copying the address and the keys from LORIOT into the device firmware - -Open `main.cpp`, and change the following lines: - -```cpp -#define LORAWAN_DEV_ADDR ( uint32_t )0x12345678 - -static uint8_t NwkSKey[] = -{ - 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6, - 0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C -}; - -// application session key -static uint8_t ArtSKey[] = -{ - 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6, - 0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C -}; -``` - -* Set `LORAWAN_DEV_ADDR` to the *big endian* DevAddr from LORIOT (green), prefixed with `0x`. -* Set `NwkSKey` and `ArtSKey` to the NWKSKEY (orange) and APPSKEY (yellow) from LORIOT, but turn them into hex numbers. For example, a LORIOT key of `5ADA30AA` should be `0x5A, 0xDA, 0x30, 0xAA` in your code. - - -#### Verifying the setup - -Now you can verify whether the setup works by clicking the *Compile* button. - -![Compile button](assets/lora10.png)Compile button - -When compilation succeeds, a file is downloaded. - -Plug your development board into the computer (over micro-USB) to mount it as a USB mass storage device. In most cases, you should not need a driver, but you can find drivers [here](https://docs.mbed.com/docs/debugging-on-mbed/en/latest/Debugging/printf/) just in case. - -Once the device mounts, drag the compiled file onto the board. This causes the device to boot up. You can then see messages coming in to the LORIOT device page: - -![We've got data!](assets/lora11.png)We've got data! - -#### Switching to manual sending - -By default, the application sends data automatically. If you want to change this, remove these lines from `main.cpp`: - -```cpp -if( txOn == true ) -{ - //Sends frame every APP_TX_DUTYCYCLE +/- APP_TX_DUTYCYCLE_RND random time (if not duty cycle limited) - os_setTimedCallback( &sendFrameJob, - os_getTime( ) + ms2osticks( APP_TX_DUTYCYCLE + randr( -APP_TX_DUTYCYCLE_RND, APP_TX_DUTYCYCLE_RND ) ), - onSendFrame ); - - ////Sends frame as soon as possible (duty cycle limitations) - //onSendFrame( NULL ); -} -``` - -You can now add code that sends a message whenever you want it to, for example when an interrupt fires because someone moves in front of the PIR sensor: - -```cpp -InterruptIn pir(D5); - -static void prepareTxFrame( void ) -{ - LMIC.frame[0] = pir; // current state of the pir sensor -#if ( LORAWAN_CONFIRMED_MSG_ON == 1 ) - LMIC.frame[1] = LMIC.seqnoDn >> 8; - LMIC.frame[2] = LMIC.seqnoDn; - LMIC.frame[3] = LMIC.rssi >> 8; - LMIC.frame[4] = LMIC.rssi; - LMIC.frame[5] = LMIC.snr; -#endif -} - -void movement() { - onSendFrame(NULL); -} - -void no_movement() { - onSendFrame(NULL); -} - -int main( void ) { - - pir.rise(movement); - pir.fall(no_movement); - - // ... lora related things -} -``` - -Change the content of the `prepareTxFrame` function to change which data you're sending (also update `LORAWAN_APP_DATA_SIZE`). You get a message whenever the PIR sensor changes state (from motion to no-motion and the other way around). - -### Using the MultiTech mDot - - -#### Importing the boilerplate program into the online IDE - -1. [Sign up](https://developer.mbed.org/account/signup/?next=%2F) for an account on ARM mbed, which hosts the Online Compiler you'll use. -1. Go to the [MultiTech mDot platform page](https://developer.mbed.org/platforms/MTS-mDot-F411/). -1. Click *Add to your mbed compiler*. -1. Go to the [mdot_personalized_activation](https://developer.mbed.org/users/janjongboom/code/mdot_personalized_activation/) project page. -1. Click *Import this program*. -1. You're redirected to the Online Compiler, where you can give the program a name. - -![Importing a program to get started](assets/lora12.png)Importing a program to get started - -**Note:** Make sure that you select the correct board in the top right corner of the compiler. - -![Selecting the right board](assets/lora13.png)Selecting the correct board - -#### Adding LORIOT keys - -Now, program the keys from LORIOT into the device firmware. - -![Copying the address and the keys from LORIOT into the device firmware](assets/lora17.png)Copying the address and the keys from LORIOT into the device firmware - -Open `main.cpp`, and copy the big endian `DevAddr` (green), the `NWKSKEY` (orange) and the `NWKSKEY` (yellow) from LORIOT into the application: - -```cpp -static const char LORIOT_DEV_ADDR[] = "AABBCCDD"; // green -static const char LORIOT_NWK_S_KEY[] = "E8A25EBD07F85800E08478A041FACBA7"; // orange -static const char LORIOT_APP_S_KEY[] = "BE8EF84E745D0AB14D4507B0BA600555"; // yellow -``` - -#### Verifying the setup - -Now you can verify whether the setup works by clicking the *Compile* button. - -![Compile button](assets/lora10.png)Compile button - -When compilation succeeds, a file is downloaded. - -Plug your development board into the computer (over micro-USB) to mount it as a USB mass storage device. In most cases, you don't need a driver, but you can find drivers [here](https://docs.mbed.com/docs/debugging-on-mbed/en/latest/Debugging/printf/) just in case. - -Once the device mounts, drag the compiled file onto the board. This causes the device to boot up. You can then see messages coming in to the LORIOT device page: - -![We've got data!](assets/lora11.png)We've got data! - -#### Switching to manual sending - -By default, the application sends data automatically. If you want to change this, remove the `send_data();` call, and call it manually (for example from an interrupt). See the [section above about the LoRa shield](#using-the-lora-shield) for more information. - -## Building a web application - -Now that the first three parts of the network are working, it's time to use the sensor data in a small application. LORIOT offers ways to get your data out of its service, but the easiest is using a websocket. You can write a web application that turns the page red when movement is detected and green when everything is OK. You do this by checking the first byte of the LoRa payload (1=movement, 0=no movement). - -1. In LORIOT: go to your dashboard, and click *Applications > Sample App > Output*. -1. Change the output type to *WebSocket*. - - ![Websocket](assets/lora14.png)Websocket - -1. Copy the URL and the token under *Current output setup*, and paste them in the code sample below: - - ![Retrieving the API parameters from the output tab in LORIOT](assets/lora16.png)Retrieving the API parameters from the output tab in LORIOT - -```html - - - - PIR Sensor monitoring! - - -

Connecting...

- - - -``` - -You now have a fully functioning LoRa network with a device, a gateway and a web application: - -![Full circle](assets/lora15.png)Full circle - -## Conclusion - -LoRa is a great technology with a lot of potential, especially because anyone can set up a network and start building long-range IoT devices with a relatively small investment. We hope this guide helped you get started, and we would love to see what you build with LoRa and ARM mbed! \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ca92484..20204c2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,5 +5,3 @@ docs_dir: docs pages: - ['index.md','LoRa on mbed'] - ['intro-to-lora.md','Building your own private LoRa network'] -- ['loriot.md','Setting up your LoRa network on LORIOT'] -- ['iotx.md','Setting up your LoRa network on IoT-X'] diff --git a/ttn-node-app/.gitignore b/ttn-node-app/.gitignore new file mode 100644 index 0000000..d570088 --- /dev/null +++ b/ttn-node-app/.gitignore @@ -0,0 +1,2 @@ +node_modules/ + diff --git a/ttn-node-app/package.json b/ttn-node-app/package.json new file mode 100644 index 0000000..837f9e4 --- /dev/null +++ b/ttn-node-app/package.json @@ -0,0 +1,32 @@ +{ + "name": "mbed-ttn-node-app", + "version": "1.0.0", + "description": "Simple web application showing data from The Things Network", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/armmbed/lora-docs.git" + }, + "keywords": [ + "lora", + "ttn", + "the things network", + "mbed", + "lorawan" + ], + "author": "Jan Jongboom ", + "license": "Apache-2.0", + "bugs": { + "url": "https://github.com/armmbed/lora-docs/issues" + }, + "homepage": "https://github.com/armmbed/lora-docs#readme", + "dependencies": { + "express": "^4.16.2", + "hbs": "^4.0.1", + "socket.io": "^2.0.4", + "ttn": "^2.3.1" + } +} diff --git a/ttn-node-app/public/ARMmbedLogo.svg b/ttn-node-app/public/ARMmbedLogo.svg new file mode 100644 index 0000000..8264ef8 --- /dev/null +++ b/ttn-node-app/public/ARMmbedLogo.svg @@ -0,0 +1 @@ +arm_mbed_lockup_horizontal \ No newline at end of file diff --git a/ttn-node-app/public/helper.js b/ttn-node-app/public/helper.js new file mode 100644 index 0000000..db5fcae --- /dev/null +++ b/ttn-node-app/public/helper.js @@ -0,0 +1,20 @@ +var notificationTo; +function showNotification(msg) { + clearTimeout(notificationTo); + + var el = document.querySelector('#notification'); + el.textContent = msg; + el.style.opacity = 1; + el.style.visibility = 'visible'; + + notificationTo = setTimeout(function() { + el.style.opacity = 0; + el.style.visibility = 'hidden'; + }, 6000); + + el.onclick = function() { + clearTimeout(notificationTo); + el.style.opacity = 0; + el.style.visibility = 'hidden'; + }; +} diff --git a/ttn-node-app/public/style.css b/ttn-node-app/public/style.css new file mode 100644 index 0000000..0e9e419 --- /dev/null +++ b/ttn-node-app/public/style.css @@ -0,0 +1,61 @@ +@import url('https://fonts.googleapis.com/css?family=Lato'); + +#header { margin-top: 20px; } +#logo { width: 167px; } +body { + font-family: "Lato", sans-serif; + margin: 0; + padding: 0 20px; + font-weight: 300; + color: rgb(80, 79, 77); + font-size: 16px; +} +h1 { + background: linear-gradient(45deg, #0091BD, #002B49); + color: white; + font-weight: 400; + font-size: 48px; + margin: 20px -20px; + padding: 30px 20px; +} +a { + color: #0091BD; + text-decoration: none; +} +a:hover { color: #333E48; } +p, li { + line-height: 23px; +} +h2 { + font-weight: 300; +} +#sensors { padding: 0; margin-top: -20px; } +#sensors li { + display: flex; + flex-direction: column; + margin: 0; + padding: 20px 0; + border-bottom: solid 1px lightgray; +} +#sensors li p { + margin: 0; +} +#sensors li label { + display: inline-block; + width: 100px; + font-weight: bold; +} + +#notification { + position: fixed; + bottom: 20px; + background: rgba(0,0,0,0.6); + color: white; + border-radius: 10px; + display: inline-block; + padding: 10px 20px; + cursor: pointer; + transition: all 0.6s ease-out; + left: 50%; + transform: translateX(-50%); +} diff --git a/ttn-node-app/server.js b/ttn-node-app/server.js new file mode 100644 index 0000000..c9577fd --- /dev/null +++ b/ttn-node-app/server.js @@ -0,0 +1,81 @@ +let TTN_APP_ID = 'YOUR_APP_ID'; +let TTN_ACCESS_KEY = 'YOUR_ACCESS_KEY'; + +const express = require('express'); +const app = express(); +const server = require('http').Server(app); +const io = require('socket.io')(server); +const hbs = require('hbs'); +const ttn = require('ttn'); + +// Some options for express (node.js web app library) +hbs.registerPartials(__dirname + '/views/partials'); +app.use(express.static(__dirname + '/public')); +app.set('view engine', 'html'); +app.set('views', __dirname + '/views'); +app.engine('html', hbs.__express); + +TTN_APP_ID = process.env['TTN_APP_ID'] || TTN_APP_ID; +TTN_ACCESS_KEY = process.env['TTN_ACCESS_KEY'] || TTN_APP_ID; + +// Store some state about all devices, you probably want to store this in a database +let devices = {}; + +// And handle requests +app.get('/', function (req, res, next) { + let d = Object.keys(devices).map(k => { + let o = { + devId: k, + last_seen: new Date(devices[k].last_seen).toLocaleString(), + state: devices[k].state + }; + return o; + }) + // Render index view, with the devices based on mapToView function + res.render('index', { devices: d }); +}); + +// Connect to TTN +console.log('Connecting to the The Things Network data channel...'); + +ttn.data(TTN_APP_ID, TTN_ACCESS_KEY).then(client => { + client.on('uplink', (devId, payload) => { + console.log('retrieved uplink', devId, payload); + + let device = devices[devId] = devices[devId] || {}; + + if (payload.port === 21) { // PIR sensor data + device.state = payload.payload_raw[0]; // check first byte + device.last_seen = Date.now(); + + // send to all connected browsers, so they can update their state + io.emit('movement-change', devId, device.state); + } + }); + + console.log('Connected to The Things Network data channel'); + console.log('Retrieving devices...'); +}).then(() => { + return ttn.application(TTN_APP_ID, TTN_ACCESS_KEY); +}).then(app => { + return app.devices(); +}).then(ttn_devices => { + console.log('Retrieved devices (' + ttn_devices.length + ')'); + + for (let t of ttn_devices) { + if (devices[t.devId]) continue; + + devices[t.devId] = { + state: -1, + last_seen: 0 + }; + } + + // Now we can start the web server + server.listen(process.env.PORT || 5270, process.env.HOST || '0.0.0.0', function () { + console.log('Web server listening on port %s!', process.env.PORT || 5270); + }); +}).catch(err => { + console.error('Could not authenticate with TTN...', err); +}); + diff --git a/ttn-node-app/views/index.html b/ttn-node-app/views/index.html new file mode 100644 index 0000000..f943488 --- /dev/null +++ b/ttn-node-app/views/index.html @@ -0,0 +1,52 @@ + + + + + LoRaWAN intruder detection + + + + + + + +

Movement sensors

+ + + + + + + + + + +