Menu

Sending Messages

In this article:

    This section shows you how to schedule messages on the Myriota Module so they can be sent to your Destination configured in Device Manager. More examples of how you might schedule messages for different types of applications can be found in the Device Code Examples.

    In a production environment, the Myriota Module requires its location and the current time in order to operate correctly. The Module will obtain this information from GNSS satellites at start up. Within the lab environment, you may not have access to a GPS signal, so we have provided alternative modes of operation that allow you to progress with your development.

    The following scenarios provide guidance on the appropriate mode, depending on the nature of your lab setup:

    1. You are able to situate your Dev Kit outside, giving you access to both the real satellite and a GPS signal
      • You can send with the Myriota Network.
      • Note that when using a satellite, you will experience Myriota Network message latency. The module will queue scheduled messages and wait for the satellite to be overhead before transmitting. 
      • This can be challenging during development. You may want to use one of the following two options to get started quickly before moving onto using the Myriota Network
    2. Your Dev Kit is situated inside, and you do not have access to a GPS signal
      • You can use Lab Mode.
      • Using Lab Mode, the Myriota Module will operate without needing a GPS fix
      • Lab Mode has the added advantage of avoiding message latency associated with the satellite network, which is useful in development and testing
    3. Your Dev Kit is situated inside, but you have access to a GPS signal via a GPS repeater, or by positioning your Dev Kit close enough to a window with an open view
      • You can use the Satellite Simulator; follow the instructions to build the "Hello, Space!" application below and see the Satellite Simulator User Guide for more details.
      • The Satellite Simulator requires the Myriota Module to have access to a GPS fix, but allows you to send messages without access to a real satellite.
      • Using the Satellite Simulator also has the added advantage of avoiding message latency associated with the satellite network, which is useful in development and testing

    Sending Messages Tutorial

    Prerequisites

    Setting Operational Modes

    The Myriota Module's mode of operation is specified when the application is compiled by setting the environment variable SATELLITES. If this environment variable is not set at build time the Module is configured in Production mode and sends messages to the Myriota Network and requires a valid GNSS fix.

    There are two lab modes available; Lab and LabWithLocation. In both lab modes the Module transmits at 434MHz at very low power which is suitable for short range communications of a few meters.

    In Lab mode, the Module's requirement of a valid GNSS fix is ignored which means location data such as device latitude and longitude is invalid. 

    LabWithLocation is used for the Satellite Simulator. In LabWithLocation a valid GNSS fix is required and location data is valid.

    Follow the steps below to learn how the Myriota Module schedules messages and build your application to transmit in the various mode.

    From Blinky to Hello, Space!

    To start programming your application, start in the SDK root directory and copy an existing example from the SDK. This command will create a folder in the SDK root directory called hello_space and copy the blinky example files.

    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 replace the line

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

    with the line (this changes the root directory path for the hello_space application as we have not created it within the examples directory)

    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 Your Application

    Build your application according to the mode of operation that you require: 

    1. Lab Mode - your Dev Kit is situated inside, and you do not have access to a GPS signal
    2. LabWithLocation - Your Dev Kit is situated inside, but you have access to a GPS signal via a GPS repeater, or by positioning your Dev Kit close enough to a window with an open view
    3. Myriota Network - You are able to situate your Dev Kit outside, giving you access to both the real satellite and a GPS signal (normal message latency)

    1. Lab Mode (no GNSS fix)

    Use the following commands to build the 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 -s -l

    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.

    2. LabWithLocation (with GNSS fix, sending via the Satellite Simulator)

    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 -s -l

    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. See the Satellite Simulator User Guide for more details.

    3. Myriota Network (with GNSS fix, sending to the real satellites)

    Build this application and program it into the Myriota Module.

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

    This builds a hello_space.bin binary that will transmit to the Myriota Network. The output from the Module's serial port will be the string "Hello, Space!" printed once at startup. 

     

    Schedule Jobs

    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(){
  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 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 (this value cannot be changed, it is defined by the Myriota Network).

    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.

    • When using the Myriota Network, the message will be transmitted when a satellite is overhead. The satellite passes can be checked from Access Times in Device Manager.
    • When using Lab or LabWithLocation mode, you can send messages more quickly by reducing the value passed to ScheduleMessage 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.

     

    Message Destinations

    Messages sent via the Satellite Simulator and the Myriota Network will be received at the Module's Destination configured in Device Manager. Depending upon the time and your location, you may need to wait up to 16 hours to receive messages sent via satellite. Messages will be received in a few minutes when sent via the Satellite Simulator (~2-10 minutes).

    Messages sent in Lab mode can be sent to the Destination using the message_inject.py script provided in the SDK tools folder. Use the commands below, replace /dev/ttyUSB0 with your USB port, replace <ID> with your Module's ID:

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

    Information about retrieving messages can be found here.

     

     

     

    Related articles