MultiTech mDot

The MultiConnect® mDot™ offers significantly longer range and improved radio performance compared to traditional wireless solutions—resulting in greater transmission range and reduced capital expense.

Overview

The MultiConnect® mDot™ is the first MBED integrated and deployable product. Featuring an FCC/CE certified LoRaWAN™ ready, Low-Power Wide Area Network (LPWAN) sub-GHz ISM band module. The mDot is capable of 2-way single-duplex communication over distances of up to 10 miles/16 km, line of sight, deep into buildings or within noisy environments in North America, Europe, and worldwide. An on board ARM Cortex-M4 processor, complete with developer friendly MBED libraries provide developers intelligence and decision making at the very edge of the network.

By leveraging LoRa™ technology, mDot simplifies local connectivity for Internet of Things (IoT) applications for the North American and European markets. By eliminating common deployment complexities, remote device connectivity is now simple and easy to deploy. With support for multiple interfaces, just about anything can now be connected with MultiTech’s mDot technology.

Key Benefits

Features

Offline Development Options

It is possible to develop offline for the mDot using mbed-cli and the Eclipse IDE. See our wiki page for more information.

Developer Kit Required

To program and use the mDot, you will need a MTUDK2-ST-MDOT Developer Kit or a MTMDK-ST-MDOT.

Exporting Not Supported

Including a bootloader in applications built for the mDot requires a post-build process. The mbed tools (online compiler & mbed-cli) automatically run this process as part of an application compilation. The mbed tools currently don't support exporting pre-bulid or post-build processes, so exports for the mDot will be incomplete and will not function.

Exporting for the mDot platform is not recommended. We will be disabling the exporter for the mDot platform in the near future so that nobody stumbles into this issue.

Instead of exporting, we recommend configuring your IDE or makefile to invoke mbed-cli to compile your application.

mbed Library Limitations

Dot libraries past version 2.0 exclusively support mbed OS version 5. Compilation using the mbed 2 SDK "classic" library will result in an error. The mbed-os library can be imported from https://github.com/armmbed/mbed-os. Most of the APIs are compatible between mbed versions, but please remember to use the right mbed library (mbed-os).

Note

MultiTech has certified the mDot for compliance with US and Foreign compliance bodies including FCC, R&TTE, and others. (e.g. FCC 15.247:2015 & IC RSS-210:2010)

MultiTech provides software meant to operate the LoRa radio to a level that maintains compliance with the operating modes under which these radio devices were certified. To ensure this level of compliance, the software code is provided in binary form only. Users are prohibited from making any changes that affect the operation of the radio performance. Accessing or controlling the radio through any means other than the provided binary software will require the user to obtain their own intentional radiator license from the certification body governing their locality, as all precertification provided with MTDOT-x will have been made invalid.



mDot Pinout Diagram

/media/uploads/mfiore/mdot-pinout-5.png

The pinout diagram above shows the commonly used interfaces and their locations. In addition to their stated functions, all GPIO pins (PA_*, PB_*, PC_*) can also be used as DigitalIn and DigitalOut interfaces.

InterruptIn Limitations

Due to the processor's architecture, only one pin of the same number (e.g. PA_1 & PB_1) may be configured as an InterruptIn. If multiple pins of the same number are configured as InterruptIn, only the last pin configured will actually trigger an interrupt in the processor. The rest will be ignored.

Pin numbers 5 - 9 are internally used as interrupts from the LoRa radio and may not be configured as external interrupts. Doing so will break the LoRa functionality of the mDot and cause undefined behavior.

Example: If the GPIO5 (PA_0) pin is configured to wake the mDot from low power modes, GPIO1 (PB_0) may not be configured as an InterruptIn. Doing so will cause the WAKE pin to not wake the mDot as desired.

PwmOut Limitations

PwmOut objects using different channels of the same timer must use the same prescaler value. Each timer has a single prescaler which applies to all channels in the timer.

For STM32F411 devices, two possible prescaler values are allowed:

  • 1us which allows for a period/pulse from 1us to 65535us
  • 500us which allows for a period/pulse from 500us to 32.76s

5V Tolerant IO Limitations

If the external voltage on a GPIO is greater than VDD + 0.3V, use of the internal pullup or pulldown resistors could damage the mDot. External pullup or pulldown resistors should be used instead.

For more information see the notes below section 6.3.1 of the STM32F411RE Data Sheet.



mDot Features



LoRa Stack (libmDot)

Dot Library Version 3 Updates

Dot Library versions 3.x.x require a channel plan to be injected into the stack. Available channel plans will be in the Dot Library repository in the plans folder.

Inject a channel plan into the stack

#include "mDot.h"
#include "ChannelPlans.h"

int main() {
    // use US915 plan
    lora::ChannelPlan* plan = new lora::ChannelPlan_US915();
    // use EU868 plan
    // lora::ChannelPlan* plan = new lora::ChannelPlan_EU868();
    assert(plan);

    mDot* dot = mDot::getInstance(plan);
    assert(dot);

    // your code ...

    return 0;
}


Revision 20 and earlier of Dot-Examples and revision 15 and earlier of Dot-AT-Firmware should be used with Dot Library versions prior to 3.0.0.

Supported Toolchains and Versions

Development and production builds of the Dot Library currently only support the ARM and GCC_ARM toolchains. The IAR toolchain is not supported at this time.

mbed-os versions prior to 5.5.0 require GCC_ARM versions 4.9 or earlier.
mbed-os versions 5.5.0 and later require GCC_ARM versions 6.0 or later.

Currently mbed-os versions 5.5.* do not work with the ARM toolchain. The online complier uses the ARM toolchain. If building offline with mbed-os 5.5.*, use the GCC_ARM toolchain version 6.0.

mDot Library Limitations

The commit messages in libmDot-mbed5 and libmDot-dev-mbed5 specify the version of the Dot library the commit contains 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.

Deepsleep functionality change

Due to the discovery of inconsistent deep sleep current draw on some mDots, libmDot versions 2.x no longer place the processor in standby mode but instead use stop mode. This means:

  • The processor no longer resets upon waking from deep sleep.
  • RAM is retained across deep sleep.
  • When invoking deep sleep the debug port will print “[WARNING] This mDot hardware version does not support deep sleep… using sleep.”

Under the hood, sleep and deep sleep now function the same with the exception of how the external IO are handled.

  • Deep sleep mode: When entering deep sleep, external pin configurations are saved and all external IO are configured as analog input with no pull resistors. This achieves lowest power consumption while mimicking how IO are configured in standby mode. Upon wake, pin configurations are restored. If having all external IO pins floating works in your installation, this mode is recommended.
  • Sleep mode: External IO configuration is left to your application. Configure pull resistors on external IO pins as required by any attached peripherals to achieve lowest power draw. It is recommended that unattached external IO pins be configured as analog inputs with no pull resistor for lowest power draw.

Please visit https://developer.mbed.org/teams/MultiTech/code/Dot-Examples/ for example code that configures the external IO for lowest power. File dot_util.cpp, found in the src directory, contains functions sleep_save_io(), sleep_restore_io() and sleep_configure_io(). These demonstrate how to configure the IO pins for lowest power consumption.

Possible flash file system corruption

Low Voltage

The file system is stored in memory that is rated for operation down to 2.7v. Accessing the flash file system when the voltage is less than 2.7v can cause the file system to become corrupted. In libmDot version 2.0.16 and later, flash file system access is blocked if the voltage is less than 2.7v. Once voltage recovers to greater than 2.8v, access to the file system is allowed.

Multitple Threads

In libmDot-dev-mbed5 version 102:8427de706d2b, a mutex was added to the flash file system to make it thread safe. This change should be included in version 63 of the release libmDot-mbed5 library. The libmDot libraries may use the flash file system to store session information and the AT command application uses the flash file system to store settings. If your application uses the flash file system and you are using a version of the library that is not thread safe, you must access the file system from the same thread as those that instantiate the mdot and command terminal objects.

Wear

The mdot flash memory part is rated for at least 100,000 write cycles per sector.

The mDot library is built against the mbed-os library (mbed 5) and is not compaible with the mbed/mbed-rtos (mbed 2). Compiling libmDot with mbed 2 will result in build failure.

Stable Production Build

This build of libmDot is stable, tested, and suitable for deployment scenarios. It is hosted on mbed and GitHub for convenience.

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.

Bleeding Edge Development Build

This build of libmDot contains bug fixes and new feature development which may not be complete. It is not guaranteed to be stable or well-tested and is not suitable for deployment scenarios. It is hosted on mbed and GitHub for convenience.

Import librarylibmDot-dev-mbed5

Bleeding edge development version of the mDot library for mbed 5. This version of the library is not guaranteed to be stable or well tested and should not be used in production or deployment scenarios.

Stack Size

In mbed 5, the default stack sizes have decreased:

  • Default main thread stack size: 4kB
  • Default other thread stack size: 2kB

It is possible to allocate a custom stack and pass it to a thread when it is created. The code snippet below demonstrates how to do this.

Create a thread with a custom stack

#include "mbed.h"

// create a 4kB stack for the thread
uint8_t t1_stack[4096];

// create the thread with custom stack
Thread t1(osPriorityNormal, sizeof(t1_stack), t1_stack);

// create the thread with default stack
//Thread t1(osPriorityNormal);

void t1_func() {
    while (true) {
        printf("hi ");
        wait(2);
    }
}

int main() {
    t1.start(t1_func);

    while (true) {
        printf("hey ");
        wait(5);
    }

    return 0;
}


If a stack overflows or the heap gets corrupted, mbed-os will detect this and report a runtime RTX error. This will cause the system to stop executing and a RTX error code will print out the debug port. If this occurs, stack sizes need to be adjusted or memory consumption needs to be reduced.



Example Programs

The following programs support multiple Dot devices. Before examples or the AT firmware are compiled, a Dot library must be imported. See the Dot-Examples or Dot-AT-Firmware landing pages for more details.

Dot Library Version 3 Updates

Dot Library versions 3.x.x require a channel plan to be injected into the stack. The Dot-Examples and Dot-AT-Firmware do this by defining a macro called "CHANNEL_PLAN" that controls the channel plan that will be used in the examples. Available channel plans will be in the Dot Library repository in the plans folder.

Revision 20 and earlier of Dot-Examples and revision 15 and earlier of Dot-AT-Firmware should be used with Dot Library versions prior to 3.0.0.

Import programDot-Examples

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

Import programDot-AT-Firmware

AT command firmware for MultiTech Dot devices.

The mbed OS API References contain example code which demonstrates how to use common peripherals like Digital IO, Analog IO, Serial, SPI, I2C, PWM, RTOS, Timers, Tickers, etc.



Factory Firmware

The mDot ships from the factory pre-loaded with our custom AT Command Firmware. This firmware provides a serial AT command interface for configuring and using the mDot. This firmware is great during development for testing LoRa transmissions and in production when using a separate host processor that controls the mDot via AT commands. It is available here. AT command documentation is available here.



Offline IDE

It is possible to compile for the mDot and debug them on the mDot using the Eclipse IDE. See our wiki page for more information.



MTS Bootloader

The mDot includes a bootloader which allows applications to be upgraded OTA (Over The Air) or via serial without the need for a developer board. See the wiki page describing how the bootloader can be used for more information.



Technical Reference

Documentation

Data Sheets



Interface Firmware

Both the UDK2 and MDK use the same ST-Link interface firmware as many of the ST Nucleo boards. The latest interface firmware and instructions for upgrading can be found here.



Getting Started with mbed

1. Connect your microcontroller to a PC

Use the USB lead to connect your mbed to a PC. The status light will come on, indicating it has power. After a few seconds of activity, the PC will recognise the mbed Microcontroller as a standard USB drive.

/media/uploads/dan/winxp-disk.png/media/uploads/dan/mac-disk.png
Windows XP exampleMac OS X example

Go to the new USB Drive, and click MBED.HTM to open it in a web browser.

If you do not have an mbed account, choose "Signup", and create your mbed Account. Otherwise, log in with your normal username and password.

This will give you access to the website, tools, libraries and documentation.



PC Configuration

Your mbed Microcontroller can appear on your computer as a serial port. On Mac and Linux, this will happen by default. For Windows, you need to install a driver:

Serial Driver for Debug Port on Windows

The DK boards for the mDot require the ST-Link driver to be installed before the debug serial port can be used on Windows PCs. This driver is different from the mbed Windows serial driver.

From a host PC to communicate with mbed you will need a terminal application. This allows the mbed Microcontroller to print to your PC screen, and for you to send characters back to your mbed.

Some terminal programs (e.g. TeraTerm) list the available serial ports by name. However, if you do need to know the identity of the serial port so that you can attach a terminal or an application to it:

WindowsMacLinux
Find the identity of the COM port by opening ''Device Manager''. To do this navigate ''Start -> Control Panel -> System -> Hardware -> Device Manager''.To find the device name under Mac OS X, use the command ''ls /dev/tty.usbmodem*''To find the device name under Linux, use the command ''ls /dev/ttyACM*''
windowsmaclinux

On both Mac and Linux PCs, the port with the higher number will be the USB serial debug port. For example, if you have Linux and get ports /dev/ttyACM0 and /dev/ttyACM1, ttyACM1 will be the debug port and ttyACM0 the AT command/secondary port.



Downloading A program

1. Save a program binary (.bin) to the Platform

Download the appropriate "Hello World!" binary. Because the UDK2 and MDK have the LED connected to different pins on the mDot, we've provided a binary for each option:

Note: the source code for this program will be seen in the next section.

Save the program binary file to your mbed Microcontroller Disk, just like you would with a normal USB disk. The Status LED will flash as the PC writes the file to the Microcontroller disk. The file is now consumed.

2. Press the Reset Button

When the Reset Button in pressed, the microcontroller will be reset and the last programmed application will begin to run.

3. Hello World!

The Microcontroller is now running the program; flashing LED1 forever! If you reset the Microcontroller, or disconnect and reconnect the power, the program will simply restart.



Hello World!

Import programmbed-os-example-blinky

This is a very simple guide, reviewing the steps required to get Blinky working on an mbed OS platform.

In its current state, the program will blink the D3 LED on a UDK2 board. To blink the RSSI LED on a MDK board, change the DigitalOut pin from LED1 to XBEE_RSSI.



Where Next

Follow the guide to creating your own programs using the online compiler



FAQ

Please log in to start a discussion or ask a question.

Questions

See more related questions