Menu

Sending Messages

In this article:

    This section shows you how to schedule messages on your Myriota device, so they can be sent to your Destination.

    More examples of how you might schedule messages for different types of applications can be found in the Module 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 device outside, giving you access to both the real satellite and a GPS signal
      • You can send messages with the Myriota Network
      • The module will queue scheduled messages and wait for the satellite to be overhead before transmitting. 
      • Often during development, you want to be able to iterate quickly without needing to wait for message delivery. The following two options can offer a faster start before moving onto using the live Network
    2. Your device is situated inside
      • 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 bypassing any latency associated with the live 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 is a lab mode available, in which 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. 

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

    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 Developer Toolkit is situated inside, and you do not have access to a GPS signal
    2. Myriota Network - You are able to situate your Developer Toolkit 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; LAB_TEST=1 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. 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 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 Myriota Network will be received at the device's assigned Destination(s). Depending upon the time and your location, you may need to wait to receive messages sent via satellite (see Message Latency for more information)

    Messages sent in Lab mode can be sent to the Destination using message injection.

     

     

     

    Related articles