Connecting your Compagno node to scriptr.io

This guide takes you step by step through building an industrial IoT proof of concept with scriptr.io, the multi-sensor wireless edge node evaluation board designed by Future Electronics, and STMicroelectronics’ STWIN SensorTile wireless industrial node development kit. This proof of concept makes use of powerful hardware allowing to you build complex and advanced industrial application, leveraging the power and versatility of scriptr.io for enterprise solutions.

This tutorial will show you how to build end to end solutions, from programming the devices all the way to the cloud enterprise software. It uses an HVAC Management application as an example.

For additional resources, we recommend you check the Compagno Development Board’s page, as well as the following Techventures with Lazina videos:

Two Ways to Read the Sensirion CO2 Sensor Values

Four Ways to Read the Panasonic GridEye Sensor

Prerequisites

Hardware

STEVAL-STWIN SensorTile (STEVAL-STWINKT1): the main board and reference design for hardware automation.
Compagno (FUT-COMPAGNO-0): multi-sensing platform extending the capabilities of the STWIN board.
NimbeLink Skywire 4G LTE CAT 1: embedded modem enabling cellular connectivity.

Software

STM32CubeProgrammer: download the STEVAL-STWIN app to the device.
Terminal tool: any compatible terminal tool such as TeraTerm.
A scriptr.io account pre-loaded with the Compagno HVAC monitoring app: specific registration steps found in section #3 below.

Recipe: Step by Step

Setting up the hardware

First, we’re going to set up all the hardware components and get them connected to a PC so we can program the device. This section details the hardware setup process.
1. Make sure the STEVAL-STWIN is not connected to anything.
2. Make sure the STLINK-V3Mini is not connected to the PC.
3. Connect the ST-Link V3MINI Programmer/Debugger board to the STWIN J2 connector, using the flat cable as shown here:
4. Make sure there’s a jumper installed on the STEVAL-STWIN 3-pin header J3, on pin 1-2 (pin 1 is farthest from the edge of the board).
  If there is no jumper, take the spare one on the Compagno board P3 header, i.e. the one installed on pin3 of P3 only, with the other socket hanging freely.
5. Make sure the Compagno board is not powered or connected to anything else.
6. Make sure there is a jumper installed on the Compagno board’s 3-pin header P3 in order to short pin 2-3 to select “EXT” (External) as the power source (pin 3 is farthest to the edge of the PCB). An external power source (˜500mA) is required to be connected to the Compagno board to power the modem at either (not both) the USB connector J1 or the Terminal block J2.
  
  Note: there could be a spare jumper installed on pin 3 of P3, but hanging freely on the other end. If it’s missing, it might have been used for the STWIN J3 header to provide power to the STMOD+ (see step 1.4 above).
7. Connect the Sensirion CO2 Sensor SCD30 to the Compagno board at connector P1 using the jumper wires.
  - The connection is pin to pin as shown below.
  - Only 5 connections are required.
  - This will leave the last 2 pins on the CO2 sensor unconnected.
8. Connect the Particulate Matter sensor Sensirion SPS30 or Panasonic SN-GCJA5 to connector P2
9. Connect the GPS antenna to the SMA connector J6
10. Install the SIM card in the Cell Modem uSD card holder
11. Install the cell modem onto the Compagno board’s J4 and J5 connectors as shown below:
12. Connect the antenna to X1 U.FL connector. For improved signal strength, you can connect a second antenna on the X2 connector of the NimbleLink Skywire module:
13. Connect the Compagno board to the STEVAL-STWIN board by joining the two 20-pin STMod connectors:
14. Connect a USB cable from the PC to the STEVAL-STWIN USB connector. This will power-up both the STEVAL-STWIN and the Compagno boards
15. Connect the External power source to the Compagno board at either the USB connector J1 or the Terminal block J2. Note that you should not use a USB hub unless it can source 500mA
16. Connect a USB cable from the PC to the STLINK-V3Mini USB connector:
17. Wait for drivers to enumerate. If this is the first time, it may take a few minutes.
Installing the software

In this step, we’re going to program the STEVAL-STWIN board by downloading the pre-compiled binary file to it.
1. Download and install the STM32CubeProgrammer software, if not already done
2. Start STM32CubeProgrammer software
3. (Optional) At this point, fee free to open a terminal window and connect to the ‘STMicroelectronics STLink Virtual COM Port’ with serial port settings 115200,8,n,1,n
4. Click the Open File tab
5. Browse to select demo firmware binary file Compagno_Project.bin and click Open
6. Click Connect if not connected
7. Click the Download button
8. When done, you will received the message “File download complete”, press OK to confirm, then verify that programming was successful
9. Click Disconnect.
  
  The software will start automatically, and you should see the below output on the terminal if you have it open:
If you did not have the terminal open, open it now, and press the reset button on the STEVAL-STWIN board to restart it. If you see nothing on the terminal, repeat steps 6-9 above.
Compagno PC software commands

Refer to this document to learn how to read the sensors’ data and execute NFC commands.
Sending data to scriptr.io

Now that the setup is working, we need to configure it to send data to the cloud. We will start by creating a scriptr.io free account with the Compagno app to receive and process the data, then we’ll configure the board to connect to it and start sending data.
1. 1. Navigate to the following link: https://www.scriptr.io/register?promocode=compagno
  2. Fill up the registration form and submit, the complete the registration process by confirming your email address.
    Notice how the Promo Code field is set to “compagno”. This will instruct scriptr.io to automatically configure your Compagno cloud application upon registration.
  3. Sign in to your scriptr.io Workspace. On your first sign in, the Compagno application will get automatically checked out from GitHub installed on your account (by running the script app/install/auto.install.scriptr). This will create the “stwincompagno” device which token will be used later on to connect to this app over a secure connection.
  4. Open the Device Directory from the top-right menu, and locate the “stwincompagno” device in the list (you should have only 2 devices in this new app). You will need to use its token in step #3.11 below. Once you reach this step, you can come back to this pop-up and click the copy button on the right of the token to copy it to your clipboard.
  5. The Compagno board ships with a SIM card from Convergia, which uses the cellular network supplier Telus, but you might need to confirm for your region. In case you need to modify the APN according to the SIM and cellular service provider, you will need to modify the STM32 application source code. You can do that under Core/Src/Cellular/Skywire.h:
  6. Now open a terminal window (115200, 8, N, 1, N) and connect to the STEVAL-STWIN board if not connected already.
  7. Issue the command cell-init to initialize the Skywire modem
    Read more ▼
    This command will:
    
    Resets the cellular modem and wait for the message +PBREADY
    
    Sends the AT command, waits for the OK message
    
    Sends ATE0 to disable the UART echo
    
    AT&K0, disable all flow control
    
    AT+CMEE=2, result code and use verbose <err> values
    
    ATV1, Long result code format: <verbose code>
    
    AT+KSLEEP=2, The UART never goes in sleep mode regardless of the DTR state
    IMPORTANT: If you don’t use this command you need to retry in less than 100ms, if you wait too much 500ms the UART won’t respond to the command.
    
    Read less ▲
  8. Issue the command cell-isonline to check if the Skywire modem is online
    Read more ▼
    This command will:
    
    Send the command +CSQ to check the signal quality. It will try 10 times. It will display the RSSI and BER
    
    Send +CGATT command, one = it is attached to the network
    
    Send +COPS?, it will display the network name
    
    Send +CGREG?,
    0,0 Not registered, home network
    0,1 Registered, home network
    0,2 Not registered, but ME is currently searching for a new operator to register to
    0,3 Registration denied
    0,4 Unknown
    0,5 Registered, roaming
    
    +CGDCONT?, display APN name and network IP
    
    Read less ▲
  9. Issue the command cell-gprs-config to configure the GPRS
    
    Read more ▼
    This command will configure +KCNXCFG for Convergia and +KCNXTIMER connection timers. The GPRS address should be the same as your APN address.
    Read less ▲
  10. Issue the following command to configure the api.scriptrapps.io endpoint:
    secure-scriptr-address 443 0 8 1
    
    Read more ▼
    This command configures the +KHTTPSCFG address for api.scriptrapps.io.
    secure-scriptr-address <https_port> <https_version> <cipher_suite> <sec_level>
    Where:
    <https_port> Numeric parameter (1-65535), use 443 for default. <https_version> 0 HTTP 1.1 (default) 1 HTTP 1.0 <cipher_suite> 0 TLS_RSA_CHOOSE_BY_SERVER 1 TLS_RSA_WITH_RC4_128_MD5 2 TLS_RSA_WITH_RC4_128_SHA 3 TLS_RSA_WITH_DES_CBC_SHA (not supported) 4 TLS_RSA_WITH_3DES_EDE_CBC_SHA (not supported) 5 TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA (not supported) 6 TLS_RSA_WITH_AES_128_CBC_SHA (tested, works) 7 TLS_RSA_WITH_AES_256_CBC_SHA (tested, works) 8 TLS_RSA_WITH_AES_128_GCM_SHA256 (tested, works) <sec_level> 1 No authentication (default) 2 Manage server authentication (renegotiation of client certificate is not supported) 3 Manage server and client authentication if requested by remote server (renegotiation of client certificate is not supported)
    
    Read less ▲
  11. Execute the below command replacing <token> with the “stwincompagno” device token from your scriptr.io Workspace (refer to step #3.4 above). This will set the authentication token allowing scriptr.io to identify the issuing device:
    scriptr-token-write <token>
  12. Before posting the data from the device to scriptr.io, execute the following command to print the payload in a JSON format and make sure all the sensors data are available and ready to be post:
    test-bodymsg
  13. You’re now ready to post the data to scriptr.io. To do that, execute the command secure-scriptr-post
    
    If successful you should be getting HTTP/1.1 200:
    
    Last part of the answer from Scriptr.io and the result of the command +KHTTPS_IND showing it is successful 200 and we sent 560 bytes:
  14. Finally, execute the command cell-http-close to close and delate the connection to scriptr.io
  Troubleshooting
  
  If you encountered any issues, refer to the troubleshooting notes below:
  - You can connect the USB port near the cellular modem to the PC to run AT commands directly to the cellular modem
  - If you don’t get a signal with the command +CSQ you need to check your antennas. Connecting the two of the them should be better but it works with one antenna. You need to make sure your cellular network supplier has coverage where you are testing.
  - If the command +COPS? shows a list of network suppliers. You need to execute the command AT+COPS=0,0,”NETWORK NAME” directly to the cellular modem USB port to get connected. Next time the cellular will get connected automatically.
  - Make sure the APN name is configured correctly in the source code define variable name APN_STRING in the file Skywire.h
  - Other helpful commands:
    - - cell-at: Send AT command for testing cellular communication
      - cell-rev: Request Revision Identification to the cellular modem
      - cell-test-get: HTTP GET for /test/dummy address in scriptr.io
      - secure-test-get: HTTPS GET for /test/dummy
      - ssl-config: Configure SSL Certificate for scriptr.io
      - secure-postman-address and secure-postman-post: Configure the address and POST message for postman-echo.com for testing
Running the application

In this final step, we will explore the scriptr.io cloud application.
1. 1. From your scriptr.io Workspace, navigate to the script hvacmonitoring/index.html and open it
  2. Click the View button to open it in your browser
  3. In the application’s login screen, enter the username and password, they’re admin/admin
  4. You will first land on a map view that will show the device on a default location on a map. If you program the device to send location data, the location will show on the transmitted coordinates
  5. Clicking on the pin will display a quick view of the sensors’ readings
  6. You can click on View Dashboard for the full dashboard view showing the latest sensor readings
  7. You can see the readings of the GridEye sensor at the bottom of the dashboard page
  8. On the top left of dashboard page, you can switch to the historical view to check how the data is changing over time
  9. For the left panel, you can select the Rules Designer to add or edit the business rules and actions related to your sensors. You can set the threshold values for each sensor so that when crossed, it would send an email notification for instance, or log the event to the cloud storage
  10. Back to the map view, when clicking on the pin, you can also click the View Alerts button to see the list of recorded events that were logged according to the rules designer. You can click on an alert to view the details corresponding to that record
1. 1. Finally, you can set who receives the notifications by clicking on Notification Settings from the top right menu.
Congratulations, you’ve completed the Compagno tutorial and built an industrial HVAC Management end-to-end proof of concept, from device to cloud. You can now start tinkering with the code and tailor it to your own needs.

Feel free to reach out to us at support@scriptr.io, whether to receive support in creating this proof concept and customizing it, or to ask for tips on taking it to production. Our team will be glad to assist you. Additionally, you can talk to a sales representative by submitting an inquiry to sales@scriptr.io to learn about our offerings.