In this article:

The Sense&Locate is shipped without a firmware application installed by default. The firmware should be programmed prior to using or deploying the device. There are 2 options for programming the Sense&Locate:

1. Use the standard SnL example application from the Myriota SDK.
2. Customise the SnL example to support sensors with longer stabilisation times, make use of the onboard vibration sensor, increase the number of messages per day, perform computations, filter sensor data or send multiple sensor readings per message.

This guide provides step by step instructions to program the Sense&Locate with the standard SnL application and describes how to customise the application using the Myriota Software Development Kit (SDK). Customisation requires competency in software development. Using the standard example is simpler however some customisation may be required depending on the parameters of the sensor used. 

Myriota can provide firmware customisation and sensor selection support. For more information, submit a support request describing your Sense&Locate application requirements.   

This guide also includes instructions to connect a sensor, register your device, send and retrieve messages via the Myriota cloud, calibrate and convert the sensor data and how to use a visualisation tool to gain data insights.

For Sense&Locate technical specifications, see the Sense&Locate Datasheet. 

Using the Myriota SnL Application

SnL Application Description

This guide uses the Myriota Sense&Locate application uses the SnL firmware application from the Myriota SDK. Without customisation, the application supports 1 sensor reading per message from a 4-20mA loop powered sensor with an operating voltage capable of 21V that has a sensor stabilisation time of less than 1500 milliseconds.

Three messages are sent to the Myriota cloud per 24 hour period. The following data is included in each message:

• Message sequence number
• Device latitude 
• Device longitude
• Time of the sensor reading
• Sensor current in microamps (uA)

Messages are received at the configured Myriota destination. This application example provides details to configure TagoIO or Eagle.io as destinations to visualise the data captured by the Sense&Locate.

The Myriota Configurator tool is used to update the device; this tool is supported only on Windows 7 and above. Details for programming the Sense&Locate using Ubuntu or macOS can be found in the Custom Application section of this guide.

The Sense&Locate application can be customised to support sensors with greater stabilisation times, to send more or less messages per day, take additional sensor readings and to perform computations or execute commands on the Myriota module itself. More details on how to create a custom application for the Sense&Locate can be found in the Custom Application section of this guide.

Application Hardware & Software Requirements

• Myriota Sense&Locate device
• PC, with internet access, running Windows 7 or above
  • To develop a customised Sense&Locate firmware application, see the requirements in the Install Myriota SDK guide.
• Myriota Configurator tool
• 4-20mA loop powered sensor, with an operating voltage capable of supporting 21V DC and a stabilisation time of less than 1.5 seconds (1500ms)
• Myriota Device Manager account (registration details can be found here)
• USB data cable
• Precision screwdrivers (Phillips and flat-head required)
• A measurement tool to compare the real-world values that your sensor is detecting and the sensor's output current (eg. a thermometer for a temperature sensor, a ruler for a level sensor)
• 2x AA lithium batteries (for deployment)
• Screws or cable ties and an appropriate mounting location (for deployment)
• TagoIO or EagleIO account (optional, to visualise your data)

Prep Your Sense&Locate 

1. Unscrew and remove the front plate to reveal the internal compartment.
2. Remove the top centre screw and the screw between the terminal block and the MicroUSB input.
3. Carefully remove the internal compartment by levering it from the bottom; removal provides easier access to the sensor gland opening.
4. Install the sensor at the bottom of the enclosure using the gland provided. 
5. 
6. Reinsert the internal compartment and screw back in place.
7. Connect the sensor to the terminal block.
   1. Sensor power input should be connected to the terminal block’s “O/→” port
   2. Sensor 4-20mA output should be connected to the terminal block’s “I/←” port
   3. For some active sensors that have an integrated MCU, the 4-20mA sensor may be one of multiple output options. In this case a ground connection may be needed to the battery’s negative terminal to provide a power loop. If you are uncertain about sensor selection or your sensor's compatibility with the Sense&Locate, contact Myriota Support.
8. Insert a microUSB data cable into the USB input port. (Do not insert batteries at this time). Note that USB cables can be power and data, or power only. Ensure you are using a data cable.

Install the Myriota Configurator

1. Follow the 'Installation Instructions' in the Myriota Configurator User Guide to install the required software dependencies and launch the tool; the Configurator is required to connect to the Sense&Locate via USB and program it with the application example. 

Program the Example Application

1. From the Configurator main menu, enter the option to 'Program Standard Examples'.
2. From the Program Standard Examples menu, enter the option for 'SnL'.
3. Connect the Sense&Locate via USB if prompted; the device will be programmed with the required files.
4. Once the programming has completed the Sense&Locate will reboot and start the application.
5. Record the module ID and registration code (these are required for device identification and registration in Device Manager).
6. Press Control + ] to exit the application.
7. Disconnect the Sense&Locate USB cable.

Register Your Sense&Locate

1. Follow the instructions in the Device Manager guide to register your Sense&Locate with the Myriota Network
   1. Use the device registration code identified during the previous step.
   2. Use the Myriota Message Store destination that is pre-configured in Device Manager, or configure a custom destination.
   3. Label your device for easy identification in Device Manager.

Sensor Calibration & Data Conversion

Before deployment, it is recommended to perform, at a minimum, a one-point calibration of the sensor to ensure accurate data conversion. Calibration involves measuring the real value that the sensor is detecting whilst recording the sensor's output (the sensor's output is in microamps (uA)). The calibration data is required to convert the sensor value to a usable, real-world data point.

Conversion formula for no calibration and two-point calibration, and example conversions for level and temperature sensors, can be found in the Calibration & Conversion Examples section.

To perform a one-point calibration and convert the sensor output (uA) to a real-world value, follow these steps:

1. Return to the Configurator main menu.
2. Enter the option for "Debug Mode".
3. Reconnect the Sense&Locate USB cable whilst holding the wakeup button on the device for more than 6 seconds; this will put the device in sensor test mode; the output in the terminal window will indicate "Sensor test mode".
4. A sensor reading will display in the Configurator GUI terminal every 5 seconds (the Sense&Locate programmable LED will also flash to indicate whether the sensor current is within the 4-20mA range; see the LED Indicators section for more details).  
   
   
   
   
5. Using a measuring tool appropriate for your sensor, measure the real-world value.
6. Record the sensor reading and the measured value; use these values in the following formula to determine the current_offset value (this value is required to calculate the conversion result):
   1.  current_offset = current - 4000 - 16000 * (measure - measure_min) / measure_span
      • current is the sensor reading in uA
      • measure is the measured value
      • measure_min is the lowest value your sensor can measure 
      • measure_span = measure_max - measure_min, where measure_max is the highest value your sensor can measure
        • For example, for a temperature sensor that can measure from -40 to +100 degrees, measure_min = -40, measure_max = 100, measure_span = 140.
7. To convert the current value read from the sensor to a real-world value, use the following formula:
   1. result = (current - 4000 - current_offset) * measure_span / 16000 + measure_min
   2. More details about the formulas can be found in the Sensor Data Conversion section.
8. Simplify the formula so that current is the only variable. Keep a record of the simplified result formula you have created; this formula will be used to convert the sensor data for data visualisation.

Install Batteries & Replace Housing

Note: The Sense&Locate will power on as soon as batteries have been inserted. To maximise battery life, do not insert the batteries and replace the housing until you are ready to deploy to a location with a clear sky view. See the Sense&Locate Deployment section below, and the Device Deployment guide, for more details. 

1. Insert 2x AA lithium batteries into the battery compartment to activate the unit; ensure they are installed with the correct polarity with the negative battery terminals positioned on the springs in the battery holder. More details about battery selection can be found in the Sense&Locate Datasheet.
2. Replace the front plate and secure the screws.
3. Your device is ready to be deployed; see the Sense&Locate Deployment section for details.
4. 8+ hours after deployment, return to this point in the guide and follow the steps below to confirm your deployment's success.

Confirm Deployment Success

To confirm that your Sense&Locate has been deployed successfully it is recommended to wait for 8-24 hours before completing the steps below. This will ensure that there have been 1 or more messages sent since the device was deployed; the SnL application firmware that was loaded in the previous steps is configured to transmit 3 messages in a 24 hour period. 

1. Log into Device Manager.
2. Select your Sense&Locate device.
3. In the device data panel, you should see data populating the 'Total/Avg Daily Messages', 'First Message' and 'Last Message' fields. 
4. The 'Avg Rx Rate' and 'Avg Tx Rate' fields are two week rolling averages; the data represented in these fields won't be meaningful until a two week period of deployment has elapsed.

More details about the telemetry available in Device Manager can be found in the Device Manager guide.

Unpack and Visualise Your Data

Messages transmitted to the Myriota network are sent as 20-byte hexadecimal strings. The SnL application message is a hexadecimal string of 18-bytes with the following format (all characters are encoded in little endian format):

• • Sequence number - unsigned 16-bit integer (2 bytes)

  • Latitude - signed 32-bit integer (4 bytes)

  • Longitude - signed 32-bit integer (4 bytes)

  • Timestamp - unsigned 32-bit integer (4 bytes)

  • Current - unsigned 32-bit integer (4 bytes)

Values must be decoded from the hexadecimal message. The configuration information required to convert the Sense&Locate application messages to useable data in both TagoIO and Eagle.io is detailed in the Configure TagoIO and Configure Eagle.io sections below.

Eagle.io and TagoIO support Myriota integration as native visualisation platforms. Before selecting your platform, we recommend reviewing both options to determine the solution that best meets your pricing and functionality requirements.

Follow the steps in the guides linked below for your selected visualisation environment; these guides will walk you through setting up the visualisation environment and configuring a new Destination in Myriota Device Manager. Replace the example information in the guides with the configuration information in the sections below.

• TagoIO
• Eagle.io

Messages can also be accessed directly from the Myriota AWS Destination using the message_store.py script available in the Myriota SDK tools folder and unpacked using the unpack.py script in the SnL example folder. See the Install Myriota SDK guide for details.

Configure TagoIO

1. Follow the instructions in the TagoIO guide.
2. Replace the example code in the TagoIO 'Run your own parser' with the code snippet below. You may need to fix the line indentation once pasting into TagoIO; a screenshot of the code in TagoIO is included below for reference. 
3. To convert the sensor current to the real-world value using the data conversion formula created earlier, edit line 14 in the screenshot below;
   1. Replace -CURRENT_OFFSET_FORMULA with the formula you created to convert the sensor current value to the real world value. 
   2. Replace X with your unit type, for example, cm for centimetres.
4. Follow the steps below to send a message from Device Manager to test your TagoIO configuration.

{ variable: 'result', value: buffer.readUInt32LE(14,17)-CURRENT_OFFSET_FORMULA, unit: 'X' },

 

 

Send a Message from Device Manager

To test the TagoIO destination, use Myriota Device Manager to send a test message.

1. From the Device Manager, Devices screen, select your Sense&Locate device.
2. Click the Send Message button; the following hex strings can be used for SnL message data.

   • 0000e01a2eeb80ae9c5268822364d7140000cccc
     [{"Sequence number": 0, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680048744, "Current": 5335}]

   • 0100e01a2eeb80ae9c52e8f22364ef2e0000cccc
     [{"Sequence number": 1, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680077544, "Current": 12015}]

   • 0200e01a2eeb80ae9c5268632464e0190000cccc

     [{"Sequence number": 2, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680106344, "Current": 6624}]

   • 0300e01a2eeb80ae9c52e8d32464354d0000cccc

     [{"Sequence number": 3, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680135144, "Current": 19765}]

   • 0400e01a2eeb80ae9c5268442564cc370000cccc

     [{"Sequence number": 4, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680163944, "Current": 14284}] 

 

TagoIO Parser Code for SnL Application

const payload_raw = payload.find(x => x.variable === 'payload_raw' || x.variable === 'payload' || x.variable === 'data');
if (payload_raw) {
  try {
    // Convert the data from Hex to Javascript Buffer.
    const buffer = Buffer.from(payload_raw.value, 'hex');

    // Extract the buffer data into variables
    const data = [
      { variable: 'seq', value: buffer.readUInt16LE(0,1) },
      { variable: 'lat', value: buffer.readInt32LE(2,5)/10000000, unit: '°' },
      { variable: 'lon', value: buffer.readInt32LE(6,9)/10000000, unit: '°' },
      { variable: 'time', value: buffer.readUInt32LE(10,13)},
      { variable: 'current', value: buffer.readUInt32LE(14,17)},

      //Edit the line below to convert the current value into the required results value.
      //Replace -CURRENT_OFFSET_FORMULA with the required numerical formula to convert your current value.
      //Replace X with your unit type. eg. m for meters
      { variable: 'result', value: buffer.readUInt32LE(14,17)-CURRENT_OFFSET_FORMULA, unit: 'X' },

    ];

    // This will concat the content sent by your device with the content generated in this payload parser.
    // It also adds the field "serie" and "time" to it, copying from your sensor data.
    payload = payload.concat(data.map(x => ({ ...x, serie: payload_raw.serie, time: payload_raw.time })));

  } catch (e) {
    // Print the error to the Live Inspector.
    console.error(e);
    
    // Return the variable parse_error for debugging.
    payload = [{ variable: 'parse_error', value: e.message }];
  }
}

Configure Eagle.io

1. Follow the steps in the Myriota guide on the Eagle.io website. Replace the tracker example information with the message format below.
   1. Append the following string to your Eagle.io configuration URL in Device Manager: /myriota?format=vllVV
   2. The Eagle.io guide provides instructions to send a message from Myriota Device Manager to test and configure the Eagle.io destination; the following hex strings can be used for the message data:

      • 0000e01a2eeb80ae9c5268822364d7140000cccc
        [{"Sequence number": 0, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680048744, "Current": 5335}]

      • 0100e01a2eeb80ae9c52e8f22364ef2e0000cccc
        [{"Sequence number": 1, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680077544, "Current": 12015}]

      • 0200e01a2eeb80ae9c5268632464e0190000cccc

        [{"Sequence number": 2, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680106344, "Current": 6624}]

      • 0300e01a2eeb80ae9c52e8d32464354d0000cccc

        [{"Sequence number": 3, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680135144, "Current": 19765}]

      • 0400e01a2eeb80ae9c5268442564cc370000cccc

        [{"Sequence number": 4, "Latitude": -34.93, "Longitude": 138.6, "Timestamp": 1680163944, "Current": 14284}] 

2. To convert the sensor current to the real-world value using the data conversion formula created earlier, from the Eagle.io Location screen, click on Parameters, click on the gear icon next to the current (V (2)) parameter.
3. Select Equation as the Transform type; enter the result formula you created to convert the sensor current value to the real world value. 
4. Enter your unit type under Units (for example, cm for centimetres) and save. 

Sense&Locate Deployment

Operating Environment

The operating environment for the Sense&Locate should be carefully considered prior to deployment. The Sense&Locate should be installed externally with a full and unobstructed view of the sky to maximise transmission success on every satellite pass. 

Physical obstacles including trees, buildings, and poles will block signals and may degrade system performance. Avoid installing the Sense&Locate within or adjacent to metal and concrete, or near other electronic equipment. Electronic interference from the surrounding environment can impact system performance and should be minimised. See the Myriota Deployment Guide for more details.

Orientation

The Sense&Locate should be mounted so that the antenna is oriented vertically, pointing up towards clear sky in all directions; hardware is included for mounting to an appropriate vertical structure.

Installation

Using Screws

1. Position the mounting plate against the install surface, ensuring the antenna is pointing up
2. Fasten the plate using screws
3. Slide the enclosure onto the mounting plate and press down to lock
4. Insert the bottom screen to secure the unit to the base plate

Mounting Sense&Locate with Internal Antenna

When deploying the Sense&Locate version 2 with an internal antenna, ensure that the top half of the device is not obstructed.

Using Cable Ties

1. Pull the cable ties through the opening in the base plate
2. Position against the required structure and secure the ties firmly
3. Slide the enclosure onto the mounting plate and press down to lock
4. Insert the bottom screen to secure the unit to the base plate

Custom Application Development

The Myriota SDK includes the SnL example application files; these can be modified to create custom firmware for the Sense&Locate. This guide describes the following customisations:

• customise sensor stabilisation time
• customise the number of messages per day  

Customising the SnL application to send multiple sensor readings per message and to perform sensor data filtering or computations is dependent on the data types and application requirements and is not included in this guide. For assistance with these types of customisations please submit a support request and describe your requirements. 

1. Follow the instructions in the Install Myriota SDK guide to set up a supported development environment.
2. The snl example application is included in the examples folder in the SDK. The main.c file contains the definition of the variables described below.
   • To customise the sensor stabilisation time, modify the value of the DELAY_MS_21V_STABILISE variable. Sensor stabilisation time may be defined as a parameter of the sensor you have selected, or it may be necessary to determine it experimentally. For more details determining the stabilisation time, see the Adjusting Stabilisation Time section below. 
   • To customise the number of messages per day modify the value of the MESSAGE_PER_DAY variable.

Adjusting Stabilisation Time

The stabilisation time may need to be modified depending on the attributes of the sensor used.  

Using the snl Example

The default stabilisation time is 1.5s. If the stabilisation time of the sensor is unknown, it is possible to increase or decrease the value of the variable DELAY_MS_21V_STABILISE in the SnL application example through trial and error to find the stabilisation boundary, and then add some buffer, say 20%.

Using a Source Measure Unit (SMU)

Power the sensor at 21V using the SMU, and measure the current consumption curve to find the stabilisation time. Reserve some buffer to the stabilization time setting.

Calibration and Conversion Examples

No Calibration

Normal accuracy. Suitable when no accurate measurement or controlled test environment is available.

Assuming current_offset = 0uA and current_span = 16000uA to be used for the calculation.

One-point Calibration

Medium accuracy. Suitable for where conditions cannot be changed easily. An accurate measurement tool is needed.

This method is to get current_offset only. Assuming current_span = 16000uA:

Two-point Calibration

High accuracy. Suitable when the sensor is under an accurately controlled calibration environment.

Firstly, get current_offset at the lowest possible reading condition. The current reading should be close to 4000uA.

measure_2  should not exceed measure_max. The bigger the gap between the two measure points is, the more accurate the calibration result will be.

Sensor Data Conversion

measure_span / current_span is also known as resolution, which means the number represented in each uA. So the equation can be written as:

• result is the real-world data such as level, pressure and temperature
• current is the uA value from the SnL
• current_offset is the difference between the expected current and the collected current, it is calculated in the calibration process
• measure_span is equal to measure_max - measure_min. For example, if a temperature sensor measures from -40℃ to 60℃, the measure_span is 100℃
• The default value of current_span is 16000uA (20000 - 4000), it might be slightly different on the real device
• measure_min is the lowest measurement the sensor can do

If no calibration is executed, the equation is:

Conversion Examples

Level Transducer

Assuming the measurement range is 0 - 3.5m. Read back current is 10000uA. So, measure_span = 3.5m and measure_min = 0m.

• No calibration

• One-point calibration

Assuming the sensor is calibrated in the open air at the deployment environment (measure = 0), the read back current is 3930uA (possible after a long time of usage).

• Two-point calibration

Assuming the read back current in 3m liquid is 17660uA (the calibration level should be as close as to 3.5m, if it is hard to create the environment, another lower level can be used such as 2m or 1m).

current_offset is the same -70uA.

Temperature Sensor

Assuming the measurement range is -40 - 60℃. In the given formula:

measure_span = 100℃ and  measure_min = -40℃.

current_offset can be calibrated at room temperature using one-point calibration or close to -40℃ for a better result using two-point calibration.

measure_span / current_span, or resolution, can be further calibrated using two-point calibration.

Sensor Testing - LED Indicators

Once the 4-20mA sensor is connected, it can be tested by following the steps below:

Deployment testing

• After power up, the device will do a sanity check of the sensor and indicate the sensor status with the LED:
  • the LED will blink once if the reading is within the normal 4-20mA interface output range
  • the LED will blink twice if the reading is out of the normal 4-20mA interface output range
  • the LED will blink three times if there is no sensor connection detected
• If actual sensor reading is needed, connect the device via the micro USB cable to the PC and use the terminal emulator mentioned above to collect output from the COM port:
  • After powerup, “Current = xxuA” and sensor reading status will be printed with the sanity check
  • After GNSS fix has been acquired, another sensor reading will be printed before the first message is scheduled
  • After that, press and hold the button for more than 1 second to trigger one more sensor reading. LED will blink once to three times depending on the reading result