installation manual - strega...

CAYENNE integration for STREGA Smart-Valves and Smart-Emitters Installation Manual

STREGA Technologies January 9, 2019 Version 1.2

CAYENNE integration for STREGA devices – User’s Manual –– v1.2 – January 9, 2019 Technical specifications may change without prior notice

1

Table of Contents The Concept ........................................................................................................................................................................... 2 Step 1. Create a free account on TTN ..................................................................................................................................... 4 Step 2. Registering your gateway on TTN............................................................................................................................... 5 Step 3. Creating an Application on TTN .................................................................................................................................. 7 Step 4. Register your STREGA device in your TTN Application ............................................................................................... 9 Step 6. Authenticating CAYENNE to your TTN account & Application .................................................................................16 Step 7. Create a CAYENNE account ......................................................................................................................................19 Step 8. Add CAYENNE integration to TTN .............................................................................................................................20 Step 9. Add the STREGA SV/SE device in CAYENNE ..............................................................................................................22

© STREGA 2019 - LoRaWANTM is a mark used under license from the LoRa AllianceTM

All rights reserved. Reproduction in whole or in part is prohibited without the prior written consent of the copyright owner. The information presented in this document does not form part of any quotation or contract, is believed to be accurate and reliable and may be changed without notice. No liability will be accepted by the publisher for any consequence of its use. Publication thereof does not convey nor imply any license under patent or other industrial or intellectual property rights. STREGA assumes no responsibility or liability whatsoever for any failure or unexpected operation resulting from misuse, neglect improper installation, repair or improper handling or unusual physical or electrical stress including, but not limited to, exposure to parameters beyond the specified maximum ratings or operation outside the specified range. STREGA PRODUCTS ARE NOT DESIGNED, INTENDED, AUTHORIZED OR WARRANTED TO BE SUITABLE FOR USE IN LIFESUPPORT APPLICATIONS, DEVICES OR SYSTEMS OR OTHER CRITICAL APPLICATIONS. INCLUSION OF STREGA PRODUCTS IN SUCH APPLICATIONS IS UNDERSTOOD TO BE UNDERTAKEN SOLELY AT THE CUSTOMER’S OWN RISK. Should a customer purchase or use STREGA products for any such unauthorized application, the customer shall indemnify and hold STREGA and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs damages and attorney fees which could arise.


2

The Concept

STREGA manufactures LoRaWAN Smart-Valve and Smart-Emitter devices. These devices are battery operated and work wirelessly using LoRa LPWAN technology. The Smart-Valve (SV) is an all-in-one valve + LoRa electronics: it mainly targets smart-metering projects:

The Smart-Emitter (SE) is like the above but…without the valve: its purpose is to connect on any irrigation valve from the market: it targets any type of IRRIGATION project:


3

Wireless Operation In popular topologies, STREGA SV (or SE) is transmitting its information wirelessly to a Receiver called a Gateway which will then transmit it to an Application Server (AS) via a Network Server (NS); the Network server is usually provided by a Telecom Operator (Orange, Vodaphone, Ooredoo, Du, Digita, Comcast, Senet, etc.), it can also be Private or even “collaborative”. The Things Network - also known as “TTN” - is a collaborative network server service. TTN provides a free of charge community network, “The Things Network”, and also a paid Enterprise solution known as “The Things Industries”. CAYENNE is an Application Server that provides a native TTN connector for handling the STREGA devices.

The security and scalability of the LoRaWAN technology is - among others - because of the network server. That is where the magic happens. TTN offers a carrier grade LoRaWAN backend allowing you to connect thousands of gateways and millions of devices. LoRaWAN technology is slow and no real time: the STREGA SV/SE sends its information to the NS and AS at slow pace in order to keep long autonomy of the batteries and to match the duty cycle limits imposed by local radio regulations (i.e. once per 15 minutes). When the SV/SE is sending data, it is called an UPLINK or UL. When CAYENNE sends something back to the Network Server then to the SV/SE via the gateway, it is called a DOWNLINK or DL. DL are necessary here to control the valve, to upload the schedulers or to modify several other parameters. DL are only taken into account when an UL is received: the DL happens directly after an UL is received from the SV/SE at the AS side. The AS, the “Application Server” is here CAYENNE that will seek its information directly to “The Things Network” (TTN). To use CAYENNE with the STREGA devices, you will first have to provision your gateway and SV/SE on TTN (or use a collaborative gateway in your area).


4

In your TTN account, you can have a long list of devices, regrouped in several “Applications”. CAYENNE will directly connect to each STREGA devices only knowing its devEUI ID.

Step 1. Create a free account on TTN The very first step is to get your account to TTN. Create a new account via the TTN Console:

https://account.thethingsnetwork.org/users/login


5

Step 2. Registering your gateway on TTN If you are located in an area where there is an active gateway provisioned on TTN already, you can skip this step and benefit from an existing coverage. To view all active collaborative gateways in your area, visit:

https://www.thethingsnetwork.org/map

If no gateway is available (yet) in your location, you will need to add one and register it to TTN, whether you make it collaborative (and accessible for all LoRaWAN sensors) or not. Adding a gateway to TTN is free of charge. So to get your Strega devices communicating to TTN, you first need to provision an active gateway onto the TTN Network Service. Information on how to register a gateway to TTN can be found here: https://www.thethingsnetwork.org/docs/gateways/registration.html


6

Ensure that your gateway is “connected” before going to the next steps !


7

Step 3. Creating an Application on TTN An Application in TTN is where you will register all your SV/SE devices from TTN standpoint. You can have many different Applications, each one supporting a list of STREGA (or other) LoRa devices. Before you can communicate with devices, you will need to add a new Application to the TTN network and register devices into it. In the CONSOLE, select “APPLICATIONS”: and add a new application:


8

Then click on the Add application button (green button down the page).


9

Step 4. Register your STREGA device in your TTN Application You can now add many STREGA devices in your Application. This registration procedure will require your device credentials that can be found using the SV-SE-READER.EXE utility. Select your Application and add a device (register device):


10

Connect your STREGA SV or SE device to the USB port and READ the parameters using the SV-SE-READER utility (see your SE/SV user’s manual for more information on this utility).

• In TTN, enter a Device ID for easy recognition (small caps only) • In TTN, enter the devEUI of your SV/SE into the Device EUI field and click on the « Register »

green button • The appEUI and the Appkey will have to be modified according to the keys that TTN will now

generate


11

WARNING: make sure you have set your STREGA SV/SE in OTAA join mode ! TTN has generated two security keys that will have to be updated in your STREGA device: copy each one by clicking on the COPY button and PASTE them in the SV-SE-READER appropriate fields.

In your STREGA device, change your appEUI and Appkey with the ones provided by TTN (do not forget to click on each Set button !!!). When done, unplug your USB cable and push on the RESET button of your device to start over with the new parameters.

COPY

VIEW


12

If all is done properly, you should now see your device communicating to the TTN console:

Click on Data section to see more live info:


13

Step 5. Adding the PAYLOAD DECODER-ENCODER The STREGA SV/SE are sending raw data according to a proprietary compacted format to optimize data communication. Each payload is providing several information on the SV/SE device status (is valve Open or Close, is lid opened or closed, remaining battery power, radio signal information, etc.). This payload should be decoded for CAYENNE that will seek the information in an understandable format. The DECODING-ENCODING procedure is performed directly on TTN. The DECODER script is required to “decrypt” all fields coming at each UL from the SV/SE. The ENCODER script is required to transmit back the various commands from CAYENNE to the SV/SE in a comprehensive format for the device. Download and unzip these two JSCRIPT files from:

www.stregauniverse.com/TTN/STREGA-ENCODER-DECODER-4TTN.zip Go to your Application and select Payload Formats:


14

Paste the DECODER script in the TTN « decoder » section then click on save payload functions button. This code will translate the STREGA UPLINK payloads into readable values for CAYENNE:

Paste the ENCODER script in the TTN « encoder » section then click on save payload functions button. This code will translate the payload coming from external applications (here CAYENNE) as DOWNLINK formatted payloads readable by the STREGA devices:


15

Your payloads are now decoded by TTN into readable information for CAYENNE:


16

Step 6. Authenticating CAYENNE to your TTN account & Application Now that you have authenticating your SV/SE device to TTN, your device is communicating securely up to the Network Server. We also need to ensure the same communication security from CAYENNE up to the Network Server to complete the top-down security chain. Securing the CAYENNE communication to TTN is done using a token algorithm computed by the Network Server. On TTN Console, load the application, and ensure you have selected Overview. Make a note of the Application ID, in the example below, it is test-eu-868:

Scroll down that page until you find Access Keys and click on manage keys:

Click on generate new access key:


17

Enter the Name of the key as cayenne-key and make sure that all checkboxes are selected. Click on the Generate Access Key button:

Your new access key will be generated:


18

Return back to the Overview page on the application:

… and scroll down the page to read the new CAYENNE-key (access key):

Click on the button to see your access key. This access key will need to be entered into CAYENNE to connect securely to TTN.


19

Step 7. Create a CAYENNE account Create an account on CAYENNE:

https://mydevices.com/cayenne/signup/


20

Step 8. Add CAYENNE integration to TTN Go back to the top of the Application page in TTN and add « CAYENNE » in the Integrations tab of your Application:


21

Select the cayenne-key you generated earlier in the appropriate Acces-key field:


22

Step 9. Add the STREGA SV/SE device in CAYENNE Create a new project and Add new device/widget:

Select LoRa and The Things Network:


23

Scroll down the list of devices until you find the STREGA Smart-Valve and Smart-Emitter devices; select what you use and go top of page !!!.

On the right of your screen, simply enter the SV/ SE devEUI of your device, then add the device to Cayenne:


24

Click left on the STREGA device you have just added: Cayenne will automatically display a default dashboard with all live parameters from your STREGA device:

You can modify all these icons and resize the widgets according to your taste. Clicking on the valve icon will directly initiate the command (DL) to TTN then to your STREGA device. Remember that LoRaWAN is no real time: your SV/SE device will only take action from the next coming UL…


25

From the event manager, you can Open/Close your valve using the Cayenne calendar:

From the trigger menu, you can send alarms or text messages to you mobile when the SV/SE is opening or closing:

installation manual - strega...

Documents