1. Open the Developer Toolkit enclosure to access the Development Board.
2. The Development Board (shown below) can be powered by USB or 2x AA lithium batteries (battery specifications can be found in the Development Board Manual). USB supplies power when both are present.
   
3. Connect your micro USB data cable to the Development Board and to your PC. If you have correctly installed the SDK and its software requirements, the Development Board's serial debug port will now be accessible. 

System Image

The System Image is a Myriota Module firmware package developed and maintained by Myriota; it is downloaded and installed using scripts from the SDK tools folder. The Install Myriota SDK guide includes detailed instructions for updating the System Image.

The System Image is SDK version dependant; devices must be flashed with the system image from the version of the SDK that their application is developed with prior to being programmed with application firmware.

The System Image performs Module and Development Board initialisation. It utilises functions from the Device API via the Board Support Package file (the bsp.c file in each example); some of the functions in the bsp.c file can be overridden with user defined functions (for example, blinky overrides the BoardStart function to implement the LED flashing sequence). Functions that are typically customised can be overridden as described in the Device API documentation.

Makefiles

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 Myriota Network Destination

Before sending messages to the Myriota Network it is necessary to register your Myriota Module with Device Manager. Follow the steps below to register the Module on your Development Board.

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; 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 - Lab Mode

To illustrate programming the Myriota Module and sending messages to the Myriota Network, we will modify the blinky example to send the message "Hello, Space!". This will send a message with a payload of hexadecimal encoded characters to the Myriota Network. We will use lab mode to avoid the Module's requirement for a valid GNSS fix; in lab mode, messages are output to the Development Board serial port and can be sent to the Device Manager Destination using a python script.

The Sending Messages guide provides details about GNSS requirements and an overview of using different lab 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 Myriota Module a job

When the Myriota 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"

time_t HelloSpace(){
   static uint16_t sequence_number;
   char message[MAX_MESSAGE_SIZE]={0};
   sprintf(message,"%04d Hello, Space!", sequence_number++);
   ScheduleMessage((uint8_t *)message, sizeof(message));
   return SecondsFromNow(30);
}

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

The Myriota 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 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 is used to schedule messages for transmission. It takes two arguments: a pointer to the message (string of chars) to be transmitted, and the number of bytes to transmit. The maximum number of bytes is 20 as given by MAX_MESSAGE_SIZE; this value cannot be changed. The maximum message size is defined by the Myriota Network communication protocol; changing this value will cause a compile error or failure.

In the example above we have programmed the HelloSpace job to run every 30 seconds in order to generate data for testing. To replicate a real world application with, for example, a schedule of 3 messages per day, we would use the function, HoursFromNow(8), to schedule a message once every 8 hours. 

The ScheduleMessage function pushes each message to the Module queue. The return value of ScheduleMessage indicates the load of the queue. 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, configure the use of Lab mode, and program the application onto the Myriota Module using the updater.py script; this builds a hello_space.bin binary.

make clean; SATELLITES=Lab make
updater.py -u hello_space.bin -s -l

Send Messages to Your Myriota Destination

To send the messages scheduled by your application to your configured Myriota Cloud Destination use the following commands, where <ID> is the Module's ID (found in Device Manager after device registration), and by replacing /dev/ttyUSB0 with your serial port identifier. 

stty 115200 sane -F /dev/ttyUSB0
stdbuf -oL awk '/TransmitMessage/{ print $5 }' /dev/ttyUSB0 | message_inject.py <ID>

Your Development Board must be connected to your PC via USB; this will power the board and start the HelloSpace application.

The command above uses the message_inject.py script from the SDK tools folder to inject messages into the Destination configured for your module in Device Manager. 

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.

Messages injected using the message_inject.py script or using the Send Message feature in Device Manager will not show as message transmission data in Device Manager but will be sent to the Destination.

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 Myriota 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 Myriota 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)

Penetrating the Developer Toolkit Enclosure

The Developer Kit enclosure can be penetrated using a drill to provide access for external sensors or other hardware. A tight-fitting gland must be used on any holes created in the enclosure to ensure the Developer Kit remains water-tight for deployment. For advice about component selection, submit a Support Ticket including a description of your requirements and component data sheets.

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