Each SDK example application includes a GNU Makefile which is used to compile the application with the required dependencies. The Makefile for the blinky example is pasted below. This Makefile uses the file main.c as the application source (and primary point of code execution) and appends the file bsp.c (or sim.c if available) to the application source. It then calls the Makefile in the module folder of the SDK which links the custom application to the System Image.

sim.c files are described within the SDK example readme files of the examples that use them.

Register Your Device & Configure Your Destination

1. Connect your Development Board to your PC via USB

2. Retrieve your registration code using the updater.py script in the SDK tools directory; enter the following command into the terminal:

   updater.py --regcode

3. Open Device Manager and follow the steps in the Device Manager Guide to create a Device Manager account, register your device and configure the message Destination. For testing, you can use the Myriota Message Store Destination that is preconfigured in Device Manager.

Tip: The SDK installation guides includes steps to add the Myriota SDK tools folder to the user's path variable. If you have added  the tools folder to your path you can run updater.py from any directory. 

"Hello, Space!" Example

To illustrate programming the Module and sending messages to the network, we will modify the blinky example to send the text message "Hello, Space!" with a counter in front of it to the UltraLite Network. The Sending Messages guide provides details about GNSS requirements and an overview of using different environments and methods of sending messages. 

Copy the Example Files & Modify the Makefile

To start programming your application, open your terminal application and copy the blinky example from the SDK into a new folder called hello_space; the line below assumes you are within the SDK/examples directory and creates the new folder in the same location.

cp -r blinky hello_space; cd hello_space

Open the Makefile in the hello_space folder. To change the application name, replace the line

PROGRAM_NAME = blinky

with the line

PROGRAM_NAME = hello_space

Give the UltraLite Module a job

When the Module first starts the AppInit function is called; this example modifies the AppInit function to call the SDK function, ScheduleJob (described below), and a new function we will define as HelloSpace.

1. Open up the main.c file in the hello_space folder and replace the contents with:

#include "myriota_user_api.h"

#define MESSAGE_SIZE    20

time_t HelloSpace(){
  static uint16_t sequence_number = 0;
  char message[MESSAGE_SIZE] = {0};
  sprintf(message, "%05d Hello, Space!", sequence_number++);

  const int id = ScheduleMessage((uint8_t *)message,sizeof(message));
  if (id >= 0) {
    printf("Successfully scheduled message of %d bytes with ID=%d\n", sizeof(message), id);
  } else {
    printf("Failed to schedule message of %d bytes\n", sizeof(message));
  }

  return HoursFromNow(4);
}

void AppInit() { ScheduleJob(HelloSpace, ASAP());

The Module is given jobs using the ScheduleJob function. The arguments of ScheduleJob are a function and the time at which the function should run. The specified function should take no arguments and return a variable of type time_t. All jobs, including system and user jobs, are scheduled in the order of their time to run. Jobs won't be preempted. The time_t returned from a job is the timestamp at which it will next run.

The ScheduleMessage function takes two arguments: a pointer to the message to be transmitted, and the number of bytes to transmit. The maximum message size that can be transmitted is dynamically determined by MessageBytesFree().

MessageBytesFree() reflects the available space for messages. It is updated each time a new message is added with ScheduleMessage, or when the transmission of a message is complete. Since SDK version 2.1.0, this API supports transmission of messages larger than the previous SDK 20-byte limit.

Additionally, MessageSlotsFree() reflects the number of free slots available in the scheduling queue. This indicates how many more messages can be scheduled for transmission before one of the messages in the queue is overwritten.

In the example above we have programmed the HelloSpace job to run every 4 hours (with HoursFromNow(4)) to replicate a real world application, so the application will schedule/send 6 messages per day in total.

The ScheduleMessage function pushes each message to the Module queue. When using the UltraLite Network, the message will be transmitted when a satellite is overhead. The satellite passes can be checked from Access Times in Device Manager.

The ScheduleMessage function pushes each message to the Module queue. The return value of ScheduleMessage indicates if the message was scheduled or not. A return value greater than one indicates that the queue is overloaded and that messages may begin to be dropped. See the Message Queue article for more details.

Compile the Application Binary File

From within the hello_space directory, use the following commands to build the application, and program the application onto the Module using the updater.py script; this builds a hello_space.bin binary.

make clean
updater.py -u hello_space.bin -s -l

Retrieve Messages

To confirm that messages have been successfully sent to your destination, use the message_store.py script from the SDK tools folder. Enter the following command into the terminal where <ID> is your module ID:

message_store.py query <ID>

All messages received at the destination will be retrieved; they must be decoded in hexadecimal format. The HelloSpace messages are in text format and can be decoded with any online hexadecimal-to-text converter.

Data Visualisation

Although not relevant for the HelloSpace example, as you build your own Myriota application you will likely generate large sets of time series data and may send multiple types of sensor readings within a single message.  Eagle.io and TagoIO are data visualisation platforms that have native Myriota integrations. These platforms can be configured as HTTP Destinations in Device Manager to directly receive device data and create customisable dashboards and alerts. Integration details can be found in the following guides:

• Eagle.io
• TagoIO

Building A Custom Application

To build a custom application, we recommend starting with one of the example applications and customising it to suit your requirements. Descriptions of the example applications and their functionality can be found in the Device Code Examples guide. For assistance developing example applications submit a Support Request describing your requirements.

Sending to the UltraLite Network

When building a custom application, we recommend building the application in lab mode to test message creation and peripheral interface connectivity before building the application for deployment. See the Sending Messages guide for more details.

Connecting Sensors & Peripheral Devices

The Developer Toolkit provides access to all of the UltraLite Module's interfaces via breakout pins. For technical specifications for the interfaces, see the Module Datasheet. The Module Integration Guide provides further details for integrating the Module into a custom device.

Functions are provided within the SDK examples and within the Device API (myriota_hardware_api.h) to implement the required communication protocols and for using the pulse counter and analogue to digital converter.   

• Inter-Integrated Circuit Interface (I²C)
• Universal Asynchronous Receiver/Transmitter (UART)
• Serial Peripheral Interface (SPI)
• Low Energy Universal Asynchronous Receiver/Transmitter (LEUART)
• Pulse Counter (PCNT)
• Analog to Digital Converter (ADC)

Assembly & Install

Step through the following instructions to assemble the Developer Toolkit in its weatherproof enclosure:

1. Attach sealing strip
2. Install two AA batteries, which can output a regulated voltage of no less than 3.0V, and connect the antenna cable to the development board
   • Non-rechargeable lithium batteries are recommended
   • The battery cover may be installed to secure the batteries
3. Close the enclosure and tighten the screws
4. Screw on the external satellite antenna
5. Install the mounting bracket, if needed

The Developer Toolkit must be installed with clear sky views to enable successful data transmission. Please review the Myriota Deployment Guide for a detailed explanation of deployment requirements.

For outside installations, the following is required:

1. The external satellite antenna and the on-board GNSS antenna (on the bottom side of the Development Board under the lid of the enclosure) require a clear view of the sky
2. The recommended mounting orientation is vertical with the external satellite antenna pointing up and the lid facing outwards
3. The enclosure should not be installed on a conducting material