Send with the Satellite Simulator

Prerequisites

  • Make sure you have already installed the SDK, set up your Toolkit, and can program the Myriota Module and read output from its serial port
  • Make sure you have your Satellite Simulator Dongle at hand
  • Place your Myriota Module in a location that has GPS coverage. Ideally you have a GPS repeater in your lab.

Set up your Satellite Simulator

The Satellite Simulator USB dongle can be used to simulate Myriota's satellite constellation within a lab environment that has a GPS signal available.

To start, plug the Satellite Simulator USB dongle into your PC and run

satellite_simulator.py

Your Satellite Simulator is now ready to receive transmissions from your Myriota Module. The Satellite Simulator passes raw information back to the Myriota Cloud for processing. After printing some output at startup, the satellite_simulator.py will not print further output during normal operation.

The Myriota Module can be told to use the Satellite Simulator by setting the environment variable SATELLITES=LabWithLocation.

The Satellite Simulator and transmit power are configured for short-range communication (a few meters) when using SATELLITES=LabWithLocation. As described above, your Myriota Module requires a GNSS fix to transmit.

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, program it into the Myriota Module, and configure use of the Satellite Simulator for transmission:

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

This builds a hello_space.bin binary that will transmit to your nearby Satellite Simulator.

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.

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, and the message will be transmitted immediately via the Satellite Simulator. 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.