In this tutorial you will learn how to build your LoRa proof of concept over scriptr.io, using the STM32L0 Discovery kit LoRa, Sigfox, low-power wireless from STMicroelectronics, and the MultiConnect® Conduit™ from MultiTech. This proof of concept features a livestock monitoring application which you can setup in less than an hour and, using scriptr.io’s online IDE, you will be able to tailor it to meet your own requirements.

If you prefer a video guide, check out this video to make sure you’re executing the steps correctly: https://youtu.be/OqVwn9Ju_Yo

Prerequisites

Hardware

Software

Recipe: Step by Step

  1. Registering for a free scriptr.io account with the B-L072Z-LRWAN1 promo code

    In this step you will need to create a scriptr.io account using the B-L072Z-LRWAN1 promotion code in order to have the B-L072Z-LRWAN1 Livestock Monitoring app automatically installed on your account, then copy the MQTT configuration to use it with the device in the subsequent steps:

    1. Create a scriptr.io account using the B-L072Z-LRWAN1 promo code using the following link in order to get the device’s app automatically installed on your account: https://www.scriptr.io/register?promocode=B-L072Z-LRWAN1
    2. Complete the registration process. For this, you need to click the link in the verification email (check the spam folder if you can’t find it).
    3. Log in to your scriptr.io Workspace.
    4. Click your username on the top right corner, then select Messaging Protocols.
    5. Under the Protocol section, make sure MQTT is selected.
    6. Under the Credentials section, select myDevice from the Device drop-down. This will display the Username and Password right under that drop-down, which you will need later.
    7. Under the Publishing Details section, select deviceDigest from the Channel drop-down. This will display the Messaging Topic right under that drop-down, which you will need later.
      messaging-protocols

  2. Setting Up Your MultiConnect® Conduit™

    The following assumes that the LoRa MultiConnect® mCard™ is already installed on the conduit. If not, please check this guide from MultiTech.

    3.1. Setting Up the Ethernet Network

    1. Connect your conduit to the network using an ethernet cable.
    2. The conduit will be accessible on a default IP address (192.168.2.1). You might need to manually change your IP to something on the same network (192.168.2.2/255.255.255.0) in order to proceed, in case your network is on a different subnet.
    3. Access the admin interface using that IP and go to Setup -> Network Interfaces where you will be able to configure the network on the conduit to fit your existing network requirements:
      1. The ethernet port we’re trying to configure is eth0, click the edit button on the right.
      2. Configure appropriately (easiest might be to set it to DHCP if your network allows that).
    4. Access the admin interface using the new IPs (either manually provided or from the DHCP) and confirm that you can still access the MultiConnect® Conduit™ under the new address:

    lora-blog-eth0-conf

    3.2. Setting Up the LoRa Network

    Since the STM32L0 connects to the Conduit™ over LoRa, this section will guide you through configuring the Conduit™ with the appropriate settings for the STM32L0. Setting up LoRa on the Conduit™ is all done from the admin interface, under LoRaWAN:

    3.2.1. Configure the Conduit™ to Work as a LoRa Network Server
    1. Under the LoRaWAN section on the left panel, go to Network Settings
    2. Set the LoRa Mode to Network Server
    3. Select the appropriate frequency based on your hardware and current location (US915 in this example)
    4. Set the Frequency Sub-Band to 1
    5. Set the Network Mode to Public LoRaWAN
    3.2.2. Add you App Key and ID
    1. Click LoRaWAN > Key Management
    2. Set the Join Server’s Location to Local Keys
    3. In Local End-Device Credentials, click on Add New
    4. Fill in the fields as follows:
      • Dev EUI: 0101010101010101
      • App EUI: 0101010101010101
      • App Key: 2B7E151628AED2A6ABF7158809CF4F3C
      • Class: A
      • Device Profile: LW102-OTA-US915
      • Network Profile: Default-CLASS-A
        end-device-key
    3.2.3. Let the Conduit Recognize Your Device
    1. Click LoRaWAN > Devices
    2. Click Add New in the upper section (End Devices)
    3. Fill the fields with the appropriate values:
      • Device EUI: 0101010101010101
      • Name: B-L072Z-LRWAN1
      • Device Profile: LW102- OTA-US915
      • Network Profile: DEFAULT-CLASS-A
        add-device
    4. From the left menu, click Save and Restart for your changes to take effect, and wait for the Conduit™ to reboot.

    3.3. Setting Up the Node-RED App

    Using Node-RED, you will create an application on the Conduit™ that will read the data sent by the STM32 device, and forward it to scriptr.io:

    1. After the Conduit™ has finished rebooting, sign back in again to the administration console
    2. Click Apps from the left panel
    3. In the Apps page, make sure the Enabled checkbox is checked under the Node-RED Apps, then click the Launch Node-RED button (if this is the first time you load Node-RED on the Conduit then it might take a while to load, be patient)
    4. If not signed-in to Node-RED, sign-in using the credentials used to log in to the administration console (admin/admin)
    5. Once in the Node-RED editor, click on the menu in the top-right corner of the screen, and go to Flow > Add to create a new flow
    6. Then go to the menu again and select Import > Clipboard
    7. Copy the below flow and paste it into the Import node dialog (image below), check the new flow option so that it gets imported in its own separate Node-RED flow, and click Import 
      [{"id":"1bc24953.c082d7","type":"lora in","z":"188cc4ab.6423eb","name":"","datatype":"bytes","x":159,"y":170.090913772583,"wires":[["e421d926.e4ba68"]]},{"id":"e421d926.e4ba68","type":"function","z":"188cc4ab.6423eb","name":"transform","func":"var oldMsg = JSON.parse(JSON.stringify(msg));\nvar msg = {\n    payload:{}\n};\n\nvar payload = parseData(oldMsg.payload); \nfor (var key in payload) {\n    msg.payload[key] = payload[key];\n}\n\nmsg.payload.deviceId = oldMsg.deveui;\nmsg.payload.time = oldMsg.time;\nreturn msg;\n\nfunction parseData(data) {\n    \n    // pressure is codes on data[2] and data[3]. If data[3] is empty, only use data[2]\n    var jsonData = {};\n    jsonData.pressure = bytesToInt(data[1], data[2], 10);\n    jsonData.temperature = bytesToInt(data[3], data[4], 100);\n    jsonData.humidity = bytesToInt(data[5], data[6], 10);\n    jsonData.batteryLevel = data[7];\n    return jsonData;\n}\n\n// this reverses the int to bytes conversion that took place on the device\nfunction bytesToInt(b1, b2, point) {\n    \n    if (!b2) {\n        return b1;\n    }\n    \n    var anInt = b1 << 8;\n    return (parseInt(anInt) + parseInt(b2)) / point;\n}","outputs":1,"noerr":0,"x":331.00000381469727,"y":230.27273178100586,"wires":[["5de80799.1f5aa8"]]},{"id":"75f73714.b3ba18","type":"comment","z":"188cc4ab.6423eb","name":"Option1 - use Lora Node _ send via MQTT","info":"","x":234.23635864257812,"y":119,"wires":[]},{"id":"5de80799.1f5aa8","type":"mqtt out","z":"188cc4ab.6423eb","name":"","topic":"","qos":"0","retain":"false","broker":"4ce4912e.07a5b","x":342.1000747680664,"y":429.09092140197754,"wires":[]},{"id":"4ce4912e.07a5b","type":"mqtt-broker","z":"","broker":"mqtt.scriptr.io","port":"1883","clientid":"","usetls":false,"compatmode":false,"keepalive":"60","cleansession":true,"willTopic":"","willQos":"0","willPayload":"","birthTopic":"","birthQos":"0","birthPayload":""}]

      import-nodes
      When you click the Import button, the imported code will get translated into the flow below. Click anywhere in the Node-RED editor to paste it.
      node-red-flow

    8. Now you need to configure the mqtt node to match your scriptr.io configuration so that it can connect to the right topic using the proper credentials. For that, you need to use the Messaging Protocols configuration parameters that you copied in the first section of this tutorial above, notably, the Username, Password and Messaging Topic.Double click the mqtt node to open its properties window, then enter the info you gathered from your scriptr.io account as shown below:
      1. In the Topic field, paste the value of the Messaging Topic from step 1.7 above
        mqtt-node-editor
      2. Then click on the pencil button next to the Server field to edit its details
      3. Switch to the Security tab, then fill in the Username and Password fields using the values you copied from your scriptr.io account in step 1.7 above
        mqtt-node-security
      4. Click Update then Done to close the node editor
    9. Click Deploy from the top right corner to deploy the newly created flow to the Conduit™

  3. Configure the STM32L0 Device

    In this section, you will configure the STM32L0 device to connect to the Conduit™ over LoRa and periodically send the X-NUCLEO-IKS01A2 sensor shield’s readings. For this, we will be using an STM32 Cube Expansion pack by STMicroelectronics and modify it accordingly.

    First, install the X-NUCLEO-IKS01A2 sensor shield on the STM32L0 board by plugging the shield’s pins into the STM32 board’s headers (make sure to push the pins all the way down).

    board-with-sensor-shield

    1. Download the I-CUBE-LRWAN package and extract it to a local folder
    2. Open the Keil μVision IDE
    3. From the Project menu, select Open Project
    4. From the dialog, locate the /en.i-cube_lrwan/STM32CubeExpansion_LRWAN_V1.2.1/Projects/B-L072Z-LRWAN1/Applications/LoRa/End_Node/MDK-ARM/Lora.uvprojx and open it, then build the project by clicking Project > Build Target. If you get the error message complaining “Device not found”, click OK and it will automatically open the Pack Installer and prompt you to install the missing device information Keil.STM32L0xx_DFP.2.0.0 – click Install. Once done, close the Pack Installer and go back to μVision. The project should open correctly in the IDE with all the required libraries.
    5. From the toolbar, click the Target Options button
      target-options
    6. Switch to the C/C++ tab and set the Define field to “STM32L072xx,USE_B_L072Z_LRWAN1,USE_HAL_DRIVER, REGION_US915,SENSOR_ENABLED,X_NUCLEO_IKS01A2” then click OK. This will set the region to US915 (change it to EU868 if you’re in Europe) and enable the sensor shield X-NUCLEO-IKS01A2.
      define-option
    7. Open the Commissioning.h file
      commissioning
    8. On line 85, set the OVER_THE_AIR_ACTIVATION constant value to 1 for OTAA (over the air activation)
    9. On line 90, set the LORAWAN_PUBLIC_NETWORK constant value to true to create a public network
    10. On line 97, set the STATIC_DEVICE_EUI constant value to 1 to freeze the Device EUI
    11. Save your changes when done
    12. Make sure your board is plugged to your PC using a USB serial cable
    13. In Keil μVision, generate a build by clicking Project > Build Target from the menu
    14. Click the load icon microvision-load in the toolbar, or press F8 (make sure that the correct project is selected on the right of the load button, i.e. mlm32l07x01)
    15. While the application is transferred to the STM32 device, a green LED will be blinking on the latter
    16. Once the LED is steady, press the black button on the STM32 board. This will initiate a join procedure with the gateway, which will take around a minute to complete, and will start sending messages with the sensors’ readings every few seconds. Feel free to connect to it using a terminal tool using a baud rate 115,200 to view the output.

    If the device successfully connected to the gateway, you should see that a new session has been created on the Conduit™:

    1. Go the Conduit™’s web console
    2. Click LoRaWAN > Device
    3. Check the session
      session

  4. Run your Scriptr.io Application

    1. Navigate to your scriptr.io Workspace
    2. Open the /livestockfitbit/index.html file and click View to open it in the browser
    3. Now that the app is running, log in using the credentials demo / demo

    You should now see it on the map since the device sends data periodically to scriptr.io (it will be shown in a predefined location since the device doesn’t send a GPS location). Zoom in on the device and click its marker/pin to see the sensors’ readings which are updated automatically every time the device sends new values. You can also see the values sent by the STM32 in the terminal if you’re connected to it.

    map-view

    You can click View Dashboard to go to a dashboard showing several charts, including time series charts showing the variations over time. This view is updated in real-time as well:

    dashboard

    You can also click View Alerts in order to see the warnings logged whenever a value exceeds a certain preset threshold:

    event-log

    Thresholds are set as rules in the Rules Designer which  you can access from the left side bar:

    rules-designer

    Here you can set several rules for each of the sensors values, i.e. temperature, humidity and pressure, which are listed in the first column of the rules designer. As you can see, in the “Rule 1” column, the first row (temperature row) reads “>8”, meaning that whenever the temperature is great than 8, an email notification is sent to the user, as indicated in the sendEmail row, and an alert is logged, as indicated in the last row corresponding to the isAlert row when set to true. Similarly, “Rule 2” means than an email alert is sent to the user whenever the humidity is greater than 30; and so on…

    In order to set the recipients of the alerts, click on the user icon on the top right corner of the screen and select Notification Settings. This will open a form allowing you to enter a comma-separated list of email addresses to receive the email alerts:

    notifications

  5. Going Forward

    Scriptr.io allows you to reduce the time to market of your IoT applications by accelerating your development pace, thanks to a plethora of API and visual development tools, such as our dashboard builder, our decision table editor, and the multitude of tools at your disposal in the Workspace.

    As you can see, you have the source code of your application in your Workspace. But before making any changes, we recommend you read the Readme.md file under the app’s folder.

    To learn more about scriptr.io, you can check out our one-page documentation as well as our how-to guides. Finally, if you have any questions or feedback, we’d love to hear from you at support@scriptr.io.