Figure 1: DC9003 mote board (left) connected to a computer via the DC9006 interface board (center).

By default, the motes in starter kits are configured for master mode; a demo mode where the API is disabled and an application is run that generates sample data and controls joining. To use the mote alongside an external MCU, the mote has to be configured for slave mode; the API is enabled and the mote expects a serially attached application to control it.

1. Start by connecting the mote to your computer via the interface board, as shown in Figure 1.
2. Identify the port name that maps to the CLI. For example, if you are in Windows and see the four COM ports pictured below, the CLI will be accessible through COM14.
    
3. Connect to the mote CLI with a third-party serial terminal of your choice (e.g. putty). See Table 1 for configuration details.

4. Use the get mode command to see the current mode:

    

   > get mode master

5. Use the set mode command to switch to slave mode, followed by reset for the change to take effect. After rebooting, a new get mode should confirm the persistent mode change.

    

   > set mode slave   > reset    > SmartMesh IP mote, ver 1.3.3.1 (0x100) > get mode slave

6. Disconnect the mote from the interface board and make sure to remove its battery (if any), as we will power the mote from the MCU.

4.2 Connect to Your Microcontroller

You will need to connect 4 wires between your MCU and the mote for power and serial communication, as shown in Table 2. In addition you need to ground the mote RX Request to Send (RTS) and TX Clear to Send (CTS); unless your MCU cannot wake on data and has to use these accordingly (the mote does not need incoming flow control).

Table 3 lists the names (equal to those found on the silkscreen) of the P1 pin header on the DC9003A mote board visible in Figure 2.

Figure 2: The DC9003A (mote) with the P1 pin header marked in red.

5 Prepare Manager

Figure 3: The DC2274A SmartMesh IP USB Manager

If you installed the correct drivers, you only have to insert the USB port in your computer: The manager will power up and start creating a network automatically.

Similar to the mote via the interface board, you should now see 4 new serial ports, where the third and fourth give you access to the CLI and API, respectively.

5.1 Factory Default Values

By default the manager is shipped with a well-known network ID and join key that your application will need to connect to its network, so you do not need to configure anything. However, it is useful to know about certain commands available through the CLI. These commands are presented in the next section, while relevant default values for its configuration parameters are listed in Table 4.

5.2 Useful CLI Commands

With the manager connected to your computer via USB:

1. Just like with the mote, identify the correct serial port name and connect to the CLI with a serial terminal of your choice (again, see Table 1 for configuration details).

2. Unlike the mote, you will first have to login to have access to the commands we want:

   login

    

   > login user

3. You now have access to a wide range of commands, where the most interesting ones are shown below.

6 User Application

This Chapter presents how to use the QSL in your application. We begin by presenting details about the API, followed by an example of how a user application might look.

More explicit examples of code are given for certain platforms in later chapters (currently only for the Raspberry Pi).

6.1 The QuickStart API

Instead of reading the full user guide for the SmartMesh IP network and mote serial API, the QuickStart Library allows you to get started with simple data publishing by familiarizing yourself with only a handful of functions. These functions define the API and are listed below, followed by a detailed explanation.

6.2 Example Application

Assuming you have downloaded the libraries and ported the necessary functions, your application simply needs to include the QSL header file, dn_qsl_api.h, and use the API as described in the previous section.

Below is a short example of how an application can send a data struct every 5 seconds, followed by parsing any downstream data received since the last transmission.

6.3 Further Tips

Base Bandwidth vs Service Request

Every mote is given a base bandwidth (service) upon joining the network (default 9000 ms) that specifies how often the mote can publish data. As noted in the QSL API, you can specify that the mote should request a specific service when connecting. However, this process can add between 20 - 60 seconds for connect to complete. Unless the motes in your network actually need individual bandwidths, you should rather change the base bandwidth granted by the manager: This is easily changed with the set config CLI command.

Change Network ID and Join Key

The default network ID and join key is well known, so unless you change these, anyone can potentially connect to your network. You can easily change both with the set config CLI command on the manager, and then use the same in your application.

Aggregate Data

If your application wants to publish data periodically etc. you should (if possible) aggregate many measurements into each transmission, rather than sending one for each measurement. The SmartMesh IP Network is designed with power consumption in mind, and its motes use very little power, except when transmitting data. Also, since the total bandwidth of a network is limited (36.4 packets/sec for the embedded manager), you will run into trouble if 40 motes requests a bandwidth to transmit messages every second (i.e. a service of 1000 ms).

Back Off Mechanism

Sending can fail if the mote is very busy. The following back off algorithm is recommended such that you only publish at a level that the network can tolerate:

• If send fails (but you are still connected), double the interval between packets. Upon subsequent failures, increase to 3x, 4x, ..., 255x.
• When send succeeds after failing, decrease the interval along the same pattern: 5x, 4x, ..., 1x.

Use the Access Control List

The manager maintains an Access Control List (ACL) which associates a mote's MAC address with a mote-specific join key. Once an ACL entry has been set, the manager will not let motes join the network that are not in the ACL. You can add a mote manually to the ACL through the set acl CLI command.

7 SimplePublish for Raspberry Pi

The QSL includes a SimplePublish example for the RPi: Along with files that implement the necessary porting functions, this example code is a single main.c file that attempts to connect with the default network ID and join key. Upon success, it starts publishing random data with an interval matching the service it requested. The example also prints any downstream user data that arrives between each transmission.

In the following sections we will guide you through the steps necessary to get the example up and running. We use a Raspberry Pi 3 Model B v1.2 running Raspbian Jessie, but the instructions will include tips on how to make it work on other models and for older versions of Raspbian.

7.1 Prepare the Raspberry Pi

We assume that you have already installed the latest release of Raspbian Jessie on a RPi, and that you wish to use the UART available on the GPIO header.

7.1.1 Disable Serial Console

The built in serial port that we want to use to communicate with the mote is by default used by the console, thus we have to disable this. To make things more complicated, the available UART has changed for the Raspberry Pi 3: The added Bluetooth module has "stolen" the high performance hardware serial port from the GPIO header; replacing it with a port that is partly software and a bit flaky. Hence, depending on which model you are using, the device name of interest to you will differ:

• Raspberry Pi 3: /dev/ttyS0
• Raspberry Pi 1-2: /dev/ttyAMA0

In Raspbian Jessie (as of May 2016) a serial port alias has been introduced to mend the effects of the changed serial portname: serial0 will point to the UART available on the GPIO header, i.e. ttyS0 for the RPi 3 and ttyAMA0 for older models. This alias is used in the SimplePublish example, thus it should work on any RPi model running the latest release of Jessie.

Enable Serial and Lock CPU Core Frequency

The serial port is disabled by default in Jessie. Also, on the RPi 3 the flaky serial port (ttyS0) can give you trouble unless you lock the CPU frequency.
To fix this, edit /boot/config.txt:

and add the following line(s) at the bottom:

Stop and Disable Getty Service 

Remove Console from Commandline

First, make a backup of /boot/cmdline.txt in case you mess something up (it contains kernel parameters):

Then edit the original:

You should see something like the example below, where serialDeviceName can be serial0 or ttyAMA0, depending on which Raspberry Pi you use.

Remove the line console=<serialDeviceName>,115200, before saving and rebooting for the changes to take effect.

7.1.2 Connect to Mote

The GPIO pins for the RPi is listed in Table 5, with the relevant pins color coded. Table 6 shows the mapping between the RPi and the mote. Note that you can of course just connect the RX RTSn and TX CTSn to GND on the mote itself, as can be seen in the example in Figure 4.

7.2 Compile and Run

This section shows you two ways to compile and run the QSL with the provided example SimplePublish code:

• Directly on the RPi with a makefile.
• Remotely on a computer using NetBeans.

The former is quick and easy, but the latter is recommended if you plan on further developing any code for the RPi.

7.2.1 Makefile
 

7.2.2 NetBeans

NetBeans is a free, open source IDE that can be installed on any OS that support Java. By simply adding the RPi as a remote build host, NetBeans will make sure to synchronize files and build the project remotely; returning any console output as you run the application on your RPi.
 

8 9 Test Downstream Data

The aforementioned DustLink apps that you can create has currently not implemented support for sending downstream messages to motes (although you might have noticed the "Fields toMote" that implies that its support is in the pipline). As an alternative, we present two simple ways to test sending downstream data to a mote. Both of these use tools part of the SmartMesh SDK, so the first thing you will have to do is to fetch this:

• If you are on Windows, the simplest way to do this is to download and unzip the latest executables from the SmartMesh SDK Release page on GitHub (look for SmartMeshSDK-X.X.X.X-win.zip).
• Otherwise, you will have to download and compile/run the Python source code directly. This has several library requirements, so it could be smart to have a look at these dustcloud installation instructions.

9.1 SimpleIPDownstreamMgr

SimpleIPDownstreamMgr is a simple console application that only asks you to specify the name of the port that the serial API of the manager is connected to (e.g. COM15). It will then connect to said manager, fetch a list of all operational motes connected to the network and start sending "Hello, World!" to each of them every 5 seconds, addressed to port 60000. The SimplePublish example application is set to listen to the same port, and should be able to parse and print the message.

9.2 APIExplorer

APIExplorer is a GUI that allows you to interact with the full API of all SmartMesh devices. The interesting API command here is sendData:

1. Set network type to SmartMesh IP, device type to manager and press load.
2. Enter the port name that the serial API of the manager is connected to (e.g. COM15) and press connect.
3. Select sendData from the command drop down list
4. Enter the necessary fields (options has to be 0) and press send.