AT Command Getting Started Guide

mDots™ are pre-loaded with custom AT Command firmware, which turns the serial interface into a command port for configuring the mDot. You can use this firmware to test LoRa connections and to develop production applications where a host processor issues AT commands to the mDot.

The AT Command Firmware is a convenient wrapper around libmDot, our mbed LoRa API. The source code is available on mbed where you can easily fork and customize it as needed.

For the AT Command Reference Guide, go to the Guides section at mDot

AT Command List

Documentation is accessible on the mDot with the help or ? commands.

help
Command Name       Description
AT      Attention  Attention
ATI     Request Id Request Identification
ATZ     Reset CPU  Reset the CPU
...

Get help for a single command using help <command>.

help AT+JOIN
AT+JOIN: Join network, provide argument of `1` to force join ...

Using Commands

Querying

Some commands allow you to query the current value. Enter the command name with no argument or followed by an optional ? to query a setting.

  • Query a value.
    AT+TXP
    11
    
    OK
  • Query a value with optional ?.
    AT+TXP?
    11
    
    OK

Assigning

Some commands allow you to assign a new value.

  • To assign a new value pass the value as an argument.
    AT+TXP=10
    
    OK
  • To see a range of input or output values for a command give ? at the only argument.
    AT+TXP=?
    AT+TXP: (0-20)
    
    OK

Examples

Network ID and Network Key can be configured with a hexadecimal value or name/passphrase.

  • To configure with a hexadecimal value provide a first argument of 0.
    AT+NI=0,0011223344556677
    
    OK
    AT+NK=0,00112233445566770011223344556677
    
    OK
  • To configure with a name/passphrase value provide a first argument of 1. When using this option, the name and passphrase are converted to hexadecimal values behind the scenes.
    AT+NI=1,MTS-LORA-1
    
    OK
    AT+NK=1,MTS-LORA-PASSPHRASE
    
    OK

Before joining to a Conduit® using the US 915 band, you must set the frequency sub-band to join using the frequencies the Conduit is configured to listen on (which set of 8 from the 64 available channels).

  • To configure the frequency sub-band
    AT+FSB=5
    
    OK

The mDot supports over-the-air (OTA) and manual join modes.

  • To configure for OTA join mode and connect to the network
    AT+NJM=1
    
    OK
    AT+JOIN
    
    OK
  • To configure for AUTO OTA join mode and connect to the network, if you are not already joined, a join attempt will be made
    AT+NJM=2
    
    OK
    Joining Network... Network Joined
    
    OK
  • To configure for MANUAL provisioning, change the mode, then set the network address and session keys (in OTA, the session keys are automatically created during the join process).
    AT+NJM=0
    
    OK
    AT+NA=0011223344556677
    
    OK
    AT+DSK=00112233445566770011223344556677
    
    OK
    AT+NSK=00112233445566770011223344556677
    
    OK

For more information, see Network Join Modes and Connecting to a Network.

Ensuring Network Connectivity

The network join status command (AT+NJS) returns a boolean value indicating network connectivity. However, the mDot can only detect a network loss by failing to receive a response from the server.  One method is to require ACKs for each packet, but under heavy load the server may be unable to respond. The other method is to only require an ACK periodically using AT+LCC which reduces the network load but still allows the mDot to detect network failures. Additionally, the link check threshold (AT+LCT) determines how many missed responses determine a network loss. In the following examples the gateway will be powered off to simulate loss of network.

  • Method one: require ACKs for each packet. With a threshold of one, after only one lost packet the network will no longer be joined. Increasing the value for LCT will allow some missed packets without having to rejoin the network. If AUTO OTA is enabled the device will attempt to rejoin after network is lost.
    [Gateway Powered On]
    AT+JOIN
    Successfully joined network
    
    OK
    AT+ACK=1
    
    OK
    AT+LCT=1
    
    OK
    AT+SEND=message
    
    OK
    [Gateway Powered Off]
    AT+NJS
    1
    
    OK
    AT+SEND=message
    Operation Timed Out - ACK not received
    
    OK
    AT+NJS
    0
    
    OK
  • Method two: only require ACKs periodically by using link checks. AT+LCC set to 2 will request a server response for every other transmitted packet. With a threshold of one, after only one missed response the network will no longer be joined. Increasing the value for LCT will allow some missed packets without having to rejoin the network. If AUTO OTA is enabled the device will attempt to rejoin after network is lost.
    [Gateway Powered On]
    AT+JOIN
    Successfully joined network
    
    OK
    AT+LCC=2
    
    OK
    AT+LCT=1
    
    OK
    AT+SEND=message
    
    OK
    [Gateway Powered Off]
    AT+SEND=message
    
    OK
    AT+NJS
    1
    
    OK
    AT+SEND=message
    Network Not Joined
    
    ERROR
    AT+NJS
    0
    
    OK

Serial Data Mode

The Serial Data mode is designed to work in conjunction with sleep where the mDot wakes up periodically, signals a host, reads data from the serial port, and then transmits it. The mDot can be configured to wake up on a fixed time interval or on an interrupt triggered by the DIO7 pin. When the mDot wakes up in serial data mode, it sets the XBEE_ON_SLEEP pin so the host processor knows when to start transmitting serial data.

This is the basic setup after configuring network settings:

  1. Set to wake-up on interval (0:INTERVAL, 1:INTERRUPT)
    AT+WM=0
  2. Set wake interval for 10 minutes
    AT+WI=600
  3. Wait for serial data for 500 ms
    AT+WD=500
  4. Timeout reading serial if no character for 20 ms
    AT+WTO=20
  5. Enable auto-join mode to join on start and save session info in flash
    AT+NJM=2
  6. Configure ACK’s or set LCC to send periodic link checks
    AT+ACK=4 (make 4 attempts to get response from server)
    or
    AT+LCC=5 (request response every 5 packets)
  7. Set number of missed responses to consider link dead and rejoin
    AT+LCT=10
  8. Configure the mDot to start in Serial Data mode
    AT+SMODE=1
  9. Save changes
    AT&W

Now if you issue AT+SD or ATZ the mDot will enter the wake-read-send-sleep cycle and monitor responses from the server to stay connected.

To escape out of serial data mode, hold SHIFT and + while pressing the reset button on the UDK. Once you see +’s being printed, press ENTER. The AT command interface should now be accessible.