Send with Lab Mode

Prerequisites

Using Lab Mode

Myriota Module requires a GNSS fix to transmit, which can be an issue when running the Module indoors. The GNSS fix can be skipped for testing purposes by setting the environment variable SATELLITES=Lab when building your application.

From Blinky to Hello, Space!

To start programming your application, copy an existing example from the SDK:

cp -r examples/blinky hello_space; cd hello_space

Open the Makefile in the hello_space folder and replace the line

PROGRAM_NAME=blinky

with the line

PROGRAM_NAME=hello_space

and the line

ROOTDIR ?= $(abspath ../..)

with the line

ROOTDIR ?= $(abspath ..)

Give the Myriota Module a job

When the Myriota Module first starts the AppInit function is called. This function can be implemented to initialise the application. Open up the main.c file in the hello_space folder and replace the contents with:

#include "myriota_user_api.h"

void AppInit() {
  printf("Hello space!\n");
}

Use the following commands to build this application, configure the use of Lab mode, and program the application into the Myriota Module:

cd hello_space;
make clean; SATELLITES=Lab make
updater.py -u hello_space.bin -p /dev/ttyUSB0 -s
(stty sane 115200; cat) < /dev/ttyUSB0

This builds a hello_space.bin binary.

The output from the Module's serial port will be the string "Hello space!" printed once at startup.

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 time_t. We call such functions jobs in what follows. All jobs, including system and user jobs, are scheduled in the order of their time to run. Jobs won't be preempted. Let's create a simple hello world type job:

#include "myriota_user_api.h"

time_t HelloSpace() {
  printf("Hello space!\n");
  return SecondsFromNow(5);
}

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

This outputs the string "Hello space!" every 5 seconds. The time_t returned from a job is the timestamp at which it will next run.

Schedule Messages

The ScheduleMessage function can be used to schedule messages for transmission. Let's modify the example code:

#include "myriota_user_api.h"

time_t HelloSpace() {
  const char message[] = "Hello space!";
  if(ScheduleMessage((uint8_t *)message, sizeof(message)) > 1)
      printf("Overloaded\n");
  return HoursFromNow(8);
}

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

The ScheduleMessage function takes two arguments: a pointer to the message to be transmitted, and the number of bytes to transmit. The maximum number of bytes is 20 as given by MAX_MESSAGE_SIZE.

The messages scheduled by your application can be sent to the destination by command using:

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

where the is Module's ID.

In the example above, we have programmed the HelloSpace job to run every 8 hours to replicate a real world application scheduling 3 messages per day. The ScheduleMessage function pushes each message to the Module queue. To get subsequent messages sending more quickly, reduce the value passed to HoursFromNow(), or use MinutesFromNow() instead.

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.