Skip to main content

FAQ Square & Puck

Q: What LoRaWAN settings should I use?​

A: When setting up your device profile or device settings in your LNS use the following settings:

  • LoRaWAN MAC version: 1.0.4
  • Regional Parameters: RP002-1.0.3
  • Max EIRP: 14

On all Square and Puck products the app/joinEUI is: 70B3D52C0001D4C3

Q: How do I join my Device?​

A: To include the Square or Puck device into your LoRa Network Server (LNS) simply add the DevEUI, AppKey and joinEUI into your server, then place the front of your device into any active NFC field. Most common Smartphones have NFC and will work. You do not need any special app, simply detecting an NFC field will trigger the device to initiate a join request. You will get a URL returned, but you do not need to open it. It's simply there to provide feedback that the NFC connection took place.

Q: How do I join my Square or Puck to a new/different LNS?​

A: The simplest way to join your device into a new LNS is to remove it from the current LNS and add it to the LNS you wish to move the device too. The link check will fail, which will unjoin the device, at which point it will rejoin again. This whole process usually takes one to two days.

With the Munin NFC app you can connect to the device over NFC and select Toggle On/Off, which will turn the device off and allow you to start the device again, which will initiate a new join request. Keep in mind that this will reboot the device and reset any custom settings you have given the unit.

Finally, if you have Roaming enabled on your device, you can add the device to multiple LoRaWAN networks simultaneously:

  1. Set the ´roamNetworkCount´ to the amount of LoRa networks you have the device added to (Min 1, max 15).
  2. Join the device with the same DevEUI and joinEUI, but increment the final bit of the appKey/nwkKey by 1 for each network, e.g. the key ´ABABABABABABABABABABABABABABAB00´ becomes ´ABABABABABABABABABABABABABABAB01´.

If the device fails to uplink to the first LNS (key ending in 00) too many times, it will try the next network in the chain (key ending in 01, then 02, and so forth) until it gets a join accept response. If the last network in the chain (based on roamNetworkCount) fails, the device will loop back to the first network and repeat the procedure. The device will stay on the network it successfully joins until it loses connection again, at which point it will start over at the beginning of the chain, so prioritize your preferred networks accordingly.

Q: How do I decode my payload?​

A: If you are using Yggio, simply select the dots-vsm-translator and you don't need to worry any further. Yggio will handle the decoding and keep track of your device applications for you.

Should you be using something other than Yggio we strongly recommend using Hugin, our MQTT client, to handle payload decoding. It— along with instructions for setting it up— can be found here: https://github.com/Sensative/vsm-mqtt-client-open-source

Using the MQTT Client has several benefits, such as ease of decoder maintenance, device management, managing the persistent data needed for payload decoding, automatic updating of device time regardless if the LNS supports it, GNSS solving capabilities, automatic GNSS almanac updating, and much more. In particular, the decoding is LNS agnostic, meaning it can easily be used for several different types of LoRa platforms or using the LoRa Network roaming feature with minimal work.

If you are looking for a more basic solution we currently do not have anything "off the shelf", though we are working on some for the more common LNSes. There is no current schedule for when this will be available however. You can use the translator Hugin uses to create your own integration if you'd like. It can be found here: https://github.com/Sensative/vsm-translator-open-source

Should you go this route we do recommend you use it as a Node Package. See https://github.com/Sensative/dots-translator-node-package-example for a very simple integration example on how to do this, along with how to use the open source translator in your own integration.

Q: Is there any app documentation?​

A: Yes, we have a public github repository with documentation for each app and app version which you can find here: https://github.com/Sensative/vsm-application-documentation/

The easiest way to find the correct documentation for the revision of the firmware on your device is to use the rulesCrc32 value that is decoded from the first uplink a device performs on port 15 and searching the repository with that number. If you are using Yggio it will be saved under the vsm field.

Q: How do I configure my Device?​

A: You can find information regarding LoRa downlink structure in the application documentation which you can find here: https://github.com/Sensative/vsm-application-documentation/

The easiest way to find the correct documentation for the revision of the firmware on your device is to use the rulesCrc32 value that is decoded from the first uplink a device performs on port 15 and searching the repository with that number. If you are using Yggio it will be saved under the vsm field.

With the Munin NFC app, you simply need to connect your phone to the device via NFC and select ´Application Settings´ and it will show you the current settings as well as allowing you to change them. Currently there is no way to configure the radar board directly in the Munin app, but there is a seperate app that can configure the device via BLE, or you can configure it over LoRa downlinks.

Q: How does my Puck Radar work?​

A: The Puck Radar product consists of two boards. The first being the Sensative Puck LoRa modem and the second one is the Acconeer XM122 radar board. When the XM122 polls the radar sensor it will always write distance and amplitude, as well as occupied status in the radar modes that supports it. When the new values are written to the Puck board, they are compared to the latest reported values and if the difference between them exceed the hysteresis values set it will uplink them both over LoRa, even if only one of them exceeds the hysteresis. If you have a occupancy sensor it is recommended to set the hysteresis on distance and amplitude so high that you only get occupancy true/false values to save on LoRa bandwith and device battery capacity.

The radar board also have a couple of different radar polling modes that work in slightly different ways. These modes are:

  • Well: The well mode reports the furthest away echo. The sensitvity level adjusts how strong the echo needs to be in order to be counted.
  • Bin: Bin mode reports the closest echo within the set distance of the sensor. The threshold level can be raised to discard any measurements with amplitudes (echo strength) below the set level. This threshold can be used to counter any noise or false positives that may be found in the polling data, though raising it too high may also cut off weak wanted echoes.
  • Parking: Parking mode reports the highest amplitude (strongest) echo within the selected distance of the sensor. Any sufficiently strong echo will also trigger the occupied value to flip to 1. Using this app you may want to raise the dista
  • Seating: Seating mode reports the closest echo within the set distance of the sensor. The threshold level can be raised to discard any measurements with amplitudes (echo strength) below the set level. This threshold can be used to counter any noise or false positives that may be found in the polling data, though raising it too high may also cut off weak wanted echoes. This app also reports an occupied flag if an object is detected three polls in a row. Three polls without any echoes will return the occupied flag to 0.

Q: What does my Square Air report?​

A: The Square Air uses the Bosch BME688, which is a sensor that detects Volitile Organic Compounds (VOCs), Volitile Sulfur Compounds (VSCs) as well as other gases such as carbon monoxide and hydrogen.

  • air_iaq: IAQ is a measaure of the indoor air quality index. It is an aggregation of several factors that attribute to poor air quality, such as VOCs etc. This value has a sliding scale, meaning it will react slower to drastic changes. Therefore the device will preform better in a mobile application.
  • air_static_iaq: IAQ is a measure of the indoor air quality index. It is an aggregation of several factors that attribute to poor air quality, such as VOCs etc. This value has a fixed scale, meaning it will react faster to changes. Therefore the device is more suited to static applications.
  • air_co2: The device comes pre-trained to estimate indoor air Co2 concentration produced by human activity by measuring the VOCs emitted by human breath and estimating the Co2 that would be accompanied by it. It does not measure the Co2 directly, the Co2 value reported by the device is only an estimate and only accurate in indoor applications where human activity is the main source of the Co2 you wish to measure. Other forms of VOC emitters may also emulate the components of human breath and give a false reading.