Example programs for MultiTech Dot devices demonstrating how to use the Dot devices and the Dot libraries for LoRa communication.

Dependencies:   ISL29011

Dependents:   Dot-Examples-delujoc

This project has moved to github

Please see GitHub Dot-Examples

Dot Library Not Included!

Because these example programs can be used for both mDot and xDot devices, the LoRa stack is not included. The libmDot library should be imported if building for mDot devices. The libxDot library should be imported if building for xDot devices.

Dot Library Limitations

Commit messages in Dot Library repositories specify the version of the library and the version of mbed-os it was compiled against. We recommend building your application with the version of mbed-os specified in the commit message of the version of the Dot library you're using. This will ensure that you don't run into any runtime issues caused by differences in the mbed-os versions.

Example Programs Description

This application contains multiple example programs. Each example demonstrates a different way to configure and use a Dot. A short summary of each example is provided below. Common code used by multiple examples is in the dot_utils.cpp file.

All examples print logging, including RX data, on the USB debug port at 115200 baud. Each example defaults the Dot's configuration and saves the new configuration to NVM.

OTA Example

This example demonstrates configuring the Dot for OTA join mode and entering sleep or deepsleep mode between transactions with the gateway. If deepsleep mode is used, the session is saved and restored so that a rejoin is not necessary after waking up even though RAM contents have been lost. ACKs are disabled, but network link checks are configured - if enough link checks are missed, the Dot will no longer be considered joined to the network and will attempt to rejoin before transmitting more data.

AUTO_OTA Example

This example demonstrates configuring the Dot for AUTO_OTA join mode and entering sleep or deepsleep mode between transactions with the gateway. AUTO_OTA join mode automatically saves and restores the session when deepsleep mode is used, so the manual saving and restoring of the session is not necessary. ACKs are disabled, but network link checks are configured - if enough link checks are missed, the Dot will no longer be considered joined to the network and will attempt to rejoin before transmitting more data.

Manual Example

This example demonstrates configuring the Dot for MANUAL join mode and entering sleep or deepsleep mode between transactions with the gateway. The Dot must be provisioned on the gateway before its packets will be accepted! Follow these steps to provision the Dot on a Conduit gateway:

  • ssh into the conduit
  • use the lorq-query application to provision the Dot on the gateway
    • lora-query -a 01020304 A 0102030401020304 <your Dot's device ID> 01020304010203040102030401020304 01020304010203040102030401020304
    • if any of the credentials change on the Dot side, they must be updated on the gateway side as well

To provision a Dot on a third-party gateway, see the gateway or network provider documentation.

Class B Example

This example demonstrates how to configure the dot for an OTA join, how to acquire a lock on a GPS synchronized beacon, and then to subsequently enter class B mode of operation. After a successful join, the device will request to the dot-library to switch to class B. When this happens, the library will send an uplink to the network server (hence we must be joined first before entering this mode) requesting the GPS time to calculate when the next beacon is expected. Once this time elapses, the dot will open an rx window to demodulate the broadcasted beacon and fire an mDotEvent::BeaconRx event upon successful reception. After the beacon is received, the example sends an uplink which will have the class B bit in the packet's frame control set to indicate to the network server that downlinks may now be scheduled on ping slots. The lora-query application can be used to configure a Conduit gateway to communicate with a Dot in class B mode. For information on how to inform a third-party gateway that a Dot is operating in class B mode, see the gateway or network provider documentation.

Class C Example

This example demonstrates configuring the Dot for OTA join mode and communicating with the gateway using class C mode. In class C mode the gateway can send a packet to the Dot at any time, so it must be listening whenever it is not transmitting. This means that the Dot cannot enter sleep or deepsleep mode. The gateway will not immediately send packets to the Dot (outside the receive windows following a transmission from the Dot) until it is informed that the Dot is operating in class C mode. The lora-query application can be used to configure a Conduit gateway to communicate with a Dot in class C mode. For information on how to inform a third-party gateway that a Dot is operating in class C mode, see the gateway or network provider documentation.

FOTA Example

Full FOTA support is available on mDot and on xDot with external flash. See this article for details on adding external flash for xDot FOTA.

Without external flash xDot can use the FOTA example to dynamically join a multicast session only. After joining the multicast session the received Fragmentation packets could be handed to a host MCU for processing and at completion the firmware can be loaded into the xDot using the bootloader and y-modem. See xDot Developer Guide.

This example demonstrates how to incorporate over-the-air updates to an application. The example uses a Class C application. Class A or B functionality could also be used. The device will automatically enter into Class C operation for the FOTA operation, Class B would be disabled during the FOTA transfer.

  • Add the following code to allow Fota to use the Dot instance

examples/src/fota_example.cpp

    // Initialize FOTA singleton
    Fota::getInstance(dot);
  • Add fragmentation and multicast handling the the PacketRx event

examples/inc/RadioEvent.h

    virtual void PacketRx(uint8_t port, uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot, uint8_t retries, uint32_t address, uint32_t fcnt, bool dupRx) {
        mDotEvent::PacketRx(port, payload, size, rssi, snr, ctrl, slot, retries, address, fcnt, dupRx);

#if ACTIVE_EXAMPLE == FOTA_EXAMPLE
        if(port == 200 || port == 201 || port == 202) {
            Fota::getInstance()->processCmd(payload, port, size);
        }
#endif
    }

A definition is needed to enable FOTA.

mbed_app.json

{
    "macros": [
        "FOTA=1"
    ]
}


Peer to Peer Example

This example demonstrates configuring Dots for peer to peer communication without a gateway. It should be compiled and run on two Dots. Peer to peer communication uses LoRa modulation but uses a single higher throughput (usually 500kHz or 250kHz) datarate. It is similar to class C operation - when a Dot isn't transmitting, it's listening for packets from the other Dot. Both Dots must be configured exactly the same for peer to peer communication to be successful.


Choosing An Example Program and Channel Plan

Only the active example is compiled. The active example can be updated by changing the ACTIVE_EXAMPLE definition in the examples/example_config.h file.

By default the OTA_EXAMPLE will be compiled and the US915 channel plan will be used.

example_config.h

#ifndef __EXAMPLE__CONFIG_H__
#define __EXAMPLE__CONFIG_H__

#define OTA_EXAMPLE              1  // see ota_example.cpp
#define AUTO_OTA_EXAMPLE         2  // see auto_ota_example.cpp
#define MANUAL_EXAMPLE           3  // see manual_example.cpp
#define PEER_TO_PEER_EXAMPLE     4  // see peer_to_peer_example.cpp
#define CLASS_C_EXAMPLE          5  // see class_c_example.cpp

// the active example is the one that will be compiled
#if !defined(ACTIVE_EXAMPLE)
#define ACTIVE_EXAMPLE  OTA_EXAMPLE
#endif

// the active channel plan is the one that will be compiled
// options are :
//      CP_US915
//      CP_AU915
//      CP_EU868
//      CP_KR920
//      CP_AS923
//      CP_AS923_JAPAN
#if !defined(CHANNEL_PLAN)
#define CHANNEL_PLAN CP_US915
#endif

#endif


Compile the AUTO_OTA_EXAMPLE and use the EU868 channel plan instead.

example_config.h

#ifndef __EXAMPLE__CONFIG_H__
#define __EXAMPLE__CONFIG_H__

#define OTA_EXAMPLE              1  // see ota_example.cpp
#define AUTO_OTA_EXAMPLE         2  // see auto_ota_example.cpp
#define MANUAL_EXAMPLE           3  // see manual_example.cpp
#define PEER_TO_PEER_EXAMPLE     4  // see peer_to_peer_example.cpp
#define CLASS_C_EXAMPLE          5  // see class_c_example.cpp

// the active example is the one that will be compiled
#if !defined(ACTIVE_EXAMPLE)
#define ACTIVE_EXAMPLE  AUTO_OTA_EXAMPLE
#endif

// the active channel plan is the one that will be compiled
// options are :
//      CP_US915
//      CP_AU915
//      CP_EU868
//      CP_KR920
//      CP_AS923
//      CP_AS923_JAPAN
#if !defined(CHANNEL_PLAN)
#define CHANNEL_PLAN CP_EU868
#endif

#endif



Dot Libraries

Stable and development libraries are available for both mDot and xDot platforms. The library chosen must match the target platform. Compiling for the mDot platform with the xDot library or vice versa will not succeed.

mDot Library

Development library for mDot.

libmDot-dev

Stable library for mDot.

libmDot-stable


For mbed-os 5 use:

Import librarylibmDot-mbed5

Stable version of the mDot library for mbed 5. This version of the library is suitable for deployment scenarios. See lastest commit message for version of mbed-os library that has been tested against.

xDot Library

Development library for xDot.

libxDot-dev

Stable library for xDot.

libxDot-stable


For mbed-os 5 use:

Import librarylibxDot-mbed5

Stable version of the xDot library for mbed 5. This version of the library is suitable for deployment scenarios.

Changes

RevisionDateWhoCommit message
42:20f6b29a9903 2021-05-25 Taylor Heck Target mbed-os 6 and Dot Library version 4. default tip
41:67feacfab49c 2020-05-18 Jason Reiss Add ServerTime event handler to RadioEvent
40:3cb0ed329c6e 2020-05-18 Jason Reiss Update type of snr argument for PacketRx handler for libmDot/libxDot 3.3.x release
39:76f8a75ed3ec 2019-12-19 Jason Reiss add preserve session
38:2c027824e046 2019-05-02 jreiss RadioEvent: remove printing packet data for FOTA example
37:cb189e6dcd1f 2019-05-02 Jason Reiss Merged FOTA to OTA default example change
36:f1053cb17d4f 2019-05-02 Jason Reiss Do not print ASCII text in FOTA example
35:cb358e793d1a 2019-05-02 jreiss Set OTA example as default
34:f6486829a451 2019-05-02 Jason Reiss Add FOTA exampe
33:15ea8f985c54 2019-04-24 jreiss Add Class B example; Update mbed-os to 5.11.1; Update mbed verison macros
32:febff0fd3195 2018-09-13 Evan Hosseini Fix update_ota_config_id_key function prototype in dot_util.h
31:b1d5811e3d5d 2018-08-23 Evan Hosseini Updates for version 3.1 of the dot library
30:2f5ae37e6c47 2018-04-30 Evan Hosseini Add ambient light sensor code back for xDot
29:9e2c0d990ace 2018-04-20 Evan Hosseini Back out NetworkMode config so code still builds with stable 3.0 library
28:558b703f621f 2018-03-15 Evan Hosseini More cleanup
27:e0a958990785 2018-03-14 Evan Hosseini Minor cleanup
26:8bdfb39a5743 2018-03-14 Evan Hosseini README updates
25:56f7775c702f 2018-03-14 Evan Hosseini Updates for the dot 3.1 release
24:d80afce304c6 2017-07-11 Mike Fiore change ret in send_data() to signed
23:4c494ddeb4fd 2017-06-30 Mike Fiore add setup script for linux/mac - clones ISL29011 library
22:d9bc10bbc433 2017-06-29 mfiore support IN865 channel plan. update mbed-os to 5.4.7
21:09d05faf0e13 2017-06-09 Mike Fiore update Dot-Examples to support Dot 3.x.x releases - new channel plans, LBT, & external channel plan functionality. Also a few bug fixes.
20:9ea0f3385ab3 2017-05-16 Mike Fiore remove libxDot
19:f8c29f84178b 2017-04-26 pferland Updated to mbed-os 5.4.2
18:b7da620f9ae3 2016-11-18 mfiore remove extra file
17:d4f82e16de5f 2016-11-01 mfiore update to mbed-os 5.1.5 (compatible with latest Dot 2.x library <2.0.16) and add note about Dot library requirement
16:a3832552dfe1 2016-10-19 Mike Fiore print mbed-os library version in examples
15:364df461110f 2016-10-11 Mike Fiore disable ACKs and enable network link checks for OTA and AUTO_OTA examples
14:19fae4509473 2016-10-11 Mike Fiore use custom event handler in all examples so RX data is displayed when received
13:f1d1ef71b3c4 2016-10-11 Mike Fiore update .hgignore
12:ec9768677cea 2016-10-11 Mike Fiore default configuration and session in each example when starting for the first time
11:d2e31743433a 2016-10-11 Mike Fiore add peer to peer example
10:4d0b765f7b9e 2016-10-10 Mike Fiore add class C example, clean up configuration display
9:72d3203279b2 2016-10-07 Mike Fiore save configuration after updating
8:e667f4a507b1 2016-10-07 Mike Fiore add manual join mode example
7:724cb82a113e 2016-10-07 Mike Fiore in sleep mode configure external IOs to achieve lowest possible current consumption
6:036c54a26c30 2016-10-07 Mike Fiore added .hgignore
5:97ed5f2f099e 2016-10-07 Mike Fiore add support for using network ID and KEY instead of name and passphrase
4:93579eb88fcd 2016-10-06 mfiore display network EUI and KEY as well as name and passphrase
3:0e3e776e2862 2016-10-06 mfiore update default credentials
2:ffac7b141b72 2016-10-06 mfiore save configuration so AUTO_OTA example works properly. clarify some comments and logging.
1:c4915e00d2ce 2016-10-06 mfiore update ISL29011 - remove enable/disable IRQ calls.; set deep_sleep to true in AUTO_OTA example.; only display frequency sub band in applicable frequency bands.
0:a151a6350d7f 2016-10-05 mfiore initial commit of OTA and AUTO_OTA examples