Versions Compared

Version Old Version 7 New Version 8
Changes made by

Former user

Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

Code Block
languagecpp
titleQuickStart API

...

bool

...

 dn_qsl_init(void);

...


bool

...

 dn_qsl_isConnected(void);

...


bool

...

 dn_qsl_connect(uint16_t netID,

...

 const

...

 uint8_t* joinKey, uint16_t srcPort, uint32_t service_ms);

...


bool

...

 dn_qsl_send(const

...

 uint8_t* payload, uint8_t payloadSize_B, uint16_t destPort);

...


uint8_t dn_qsl_read(uint8_t* readBuffer);

 

 

Panel

init

Upon startup, this always has to be run once. It will initialize the necessary structures and underlying modules, essentially establishing a serial connection to the Mote.

Parameters: None

Returns: Boolean indicating the success of the initialization. However, currently it will always return TRUE: The underlying init functions of the SmartMesh C Library does not have any return values (it is still included for forward compatability if these init functions are changed to include return values).

Panel

isConnected

Simple TRUE/FALSE query to QSL if the mote is currently connected to the SMIP network and ready to send/receive data. This way, the user application can check if it should reconnect (call connect again) in the case of a failed send (or if the send simply failed).

Parameters: None

Returns: Booleanindicating if the mote is connected to a network.

Panel

connect

Run after a successful init to make the mote search and join a network with the given network ID and join key, followed by requesting the given service. Further, a socket is opened and bound to the given port, ready to send/receive user data.

Subsequent calls to connect while still connected has a few different behaviours based on the parameter values:

  • A different network ID, join key and/or port will cause the mote to attempt to reconnect with the new parameters.
  • If only the requested service is different, the mote will simply make a new request.
  • If all parameters are the same, connect simply returns TRUE, essentially a way to check that the mote is still connected with the given parameters.

Parameters:

  • netID: The ID of the network the mote should attempt to join. If 0, the default ID is used. If 0xFFFF, the mote will join the first network heard.
  • joinKey: The join key to use in the connection attempt. If NULL, the default key is used.
  • srcPort: The port to expect downstream data on. If 0, the default port is used.
  • service_ms: The service to request after establishing a connection, given in milliseconds. If 0, no mote specific service is requested (and the user application should adhere to the base bandwidth granted by the manager).

Returns: Boolean indicating if the mote successfully connected to a network and was granted the requested service, if any.

Panel

send

If connected to a network, the mote will send a packet with the given payload to the given port. The packet is addressed to the manager by default, but it is possible to change this to any IPv6 address with the DN_DEST_IP define (this will require that the manager is connected to a computer correctly configured as a gateway, e.g. by using DustLink). Note that end-to-end delivery is not guaranteed with the utilized UDP, but the success rate of the mesh network is typically greater than 99.9 %.

Parameters:

  • payload: Pointer to a byte array containing the payload.
  • payloadSize_B: Byte size of the payload.
  • destPort: The destination port for the packet. If 0, the default port is used.

Returns: A boolean indicating if the packet was queued up for transmission at the mote.

Panel

read

The payload of downstream messages are pushed into a buffered FIFO inbox as they arrive. Calling read will pop the first one (oldest) stored into the provided buffer and return the byte size; 0 indicates that the inbox is empty. As the inbox has a limited size (can be changed with the DN_INBOX_SIZE define), old data will start to drop if the user application does not make sure to call read often enough.

Parameters:

  • readBuffer: Pointer to a byte array to store the read message payload.

Returns: The number of bytes read into the provided buffer.

 

...

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.
 

 

Code Block
languagecpp
titleExample usage of QuickStart API
#include <stdlib.h>
#include "dn_qsl_api.h"

#define NETID           0       // Factory default value used if zero (1229)
#define JOINKEY         NULL    // Factory default value used if NULL (44 55 53 54 4E 45 54 57 4F 52 4B 53 52 4F 43 4B)
#define BANDWIDTH_MS    5000	// Not changed if zero (default base bandwidth given by manager is 9 s)
#define SRC_PORT		0		// Default port used if zero (0xf0b8)
#define DEST_PORT       0		// Default port used if zero (0xf0b8)

int main(void)
{
    my_data_struct_t myData;
    uint8_t bytesRead;
    uint8_t* myBuffer[DN_DEFAULT_PAYLOAD_SIZE_LIMIT];

    if (!dn_qsl_init())
    {
        return; // Initialization failed
    }

    while (TRUE)
	{
		if (dn_qsl_isConnected())
		{
			/*
			Prepare myData
			*/
			
			if (!dn_qsl_send(&myData, sizeof (myData), DEST_PORT))
			{
				// Pushing data to the manager failed
			}

			do
			{
				bytesRead = dn_qsl_read(inboxBuf);
				/*
				Parse received data
				*/
			} while (bytesRead > 0);
			
			/*
			Wait for next transmission (5000 ms)
			*/
		} else
		{
			if (dn_qsl_connect(netID, joinKey, srcPort, service_ms))
			{
				// Connected to network
			} else
			{
				// Failed to connect
			}
		}
	}

	return (EXIT_SUCCESS);
}

 

...