Schedule Messages

This section describes some simple applications with the Myriota Module. Further examples can be found in the examples directory.

It is assumed that you have installed the SDK, set up your Toolkit, and can program the Myriota Module and read output from its serial port.

To operate correctly, the Myriota Module requires its location and the current time. The Module will obtain this information from GNSS satellites at startup. To run the examples in this section it is necessary to place your Myriota Module in a location that has GPS coverage. Ideally you have a GPS repeater in your lab. You can otherwise use this as an opportunity to work outside.

From Blinky to Hello, Space!

Start by copying an existing example:

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");
}

Build this application and program it into the Myriota Module.

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

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 HelloSpace job runs every 8 hours in the example above corresponding with 3 messages transmitted per day. ScheduleMessage does not immediately transmit your message. The message is placed in a queue and will be transmitted when a satellite is overhead. The return value of ScheduleMessage indicates the load of the queue. A return value greater than one indicate that the queue is overloaded and that messages may begin to be dropped.

Depending upon the time and your location, you may need to wait up to 16 hours to receive messages sent via satellite. If you do not wish to wait then you can set up a Satellite Simulator to simulate a Myriota satellite in your lab.

Next Step: Using the Satellite Simulator