-
Notifications
You must be signed in to change notification settings - Fork 15
Getting Started
This repository contains a full implementation of the Sparrow application layer protocol and tools needed to make use of it. The implementation is based on Contiki OS and some of the popular platforms are supported from start.
Sparrow is communicating on top of IPv6/UDP and defines an encapsulation format (called encap) that encapsulates different types of payload. The most important payload is the TLV payload. This is used for all of the application data to and from IoT devices running Sparrow. TLVs consist of type, length and values and are fairly similar to OMA TLVs used in OMA LWM2M.
The application layer also defines an object model where each IoT device can present a number of object instances at runtime. There is a discovery procedure to discover the number of object that any IoT device implements and their type. Any Sparrow device defines Instance 0 - that is a management and discovery instance. Instance 0 has one variable that describe the number of instances available on this device. After knowing the instance count, all other instances can be discovered (e.g. read out type of object, and other parameters).
Start by checking out needed submodules. Contiki OS is included as a git submodule (and recursive is used to get Contiki's submodules out).
> cd sparrow
> git submodule update --init --recursive
In the repository there is also a set of tools needed for creating OTA images and to upload these images.
To create an image for a device do the following:
> cd examples/felicia/iot-u10
> make images
> ....
> make upload-fast DST=fd00::1234:1234:1234:1234
> ....
The newly built image will be uploaded to the device with that specific address. Note: you need to run a border router to enable the node to join an RPL/6LoWPAN network and reachable by the upload tool. See instructions here: Border Router.
There is an example application included for testing with Zolertia RE-MOTE. To begin with, the RE-MOTE needs to be programmed with a rescue image that contains the Sparrow bootloader. The RE-MOTE can always be reprogrammed again using the serial bootloader so it is no problems reprogramming the RE-MOTE later with another non-Sparrow application.
To ease use, a prebuilt Sparrow bootloader binary is included and used by default when building rescue images for CC2538 based platforms. The source code for the bootloader is available in cpu/cc2538/bootloader.
First create a rescue-image that includes the bootloader.
> cd examples/zoul/remote
> make IMAGE=1
> make rescue-image
Make sure the RE-MOTE is connected via USB
> make upload-rescue-image
Now the RE-MOTE should be running an example application where it is possible to control the LEDs and listen to the user button using the Sparrow application layer. Make sure you have a border router running and wait for the RE-MOTE to connect to your network before trying to communicate with the node.
To see when the node is joined you can use:
> wget -qO- http://[fd02::212:4b00:60e:772]/r
fd02::212:4b00:615:9b95
The address to do wget to is the one that the border router prints at start.
In this case there is a node joined and given that this is a Zolertia RE-MOTE the
LEDs can be toggled using a Python script. The Python scripts are in the folder tools/sparrow.
> cd tools/sparrow
> ./leds.py fd02::212:4b00:615:9b95 toggle 1
This should toggle the blue LED (or the blue color on the ReMote).
Start by creating an image archive for OTA. An image archive contains both images which makes it easy for the upload tool to simply upload the image for the container that is currently not used in the node.
NOTE: Remember to always increase the INC number when recompiling during each day to mark the newly compiled image as newer than the previous image. If both images have the same date and same INC, the first one will be used when booting.
> cd examples/zoul/remote
> make images INC=0
> make upload-fast DST=<IP-address-of-the-RE-MOTE-node>
The make rule upload-fast can be used for faster update of locally
connected (single hop) nodes. The make rule upload uses a slower
update process that can be used for multihop networks or to avoid
affecting the network during updates.
During bootup, before the application is started, the Zoul RE-MOTE will blink once if booting on the first image, and twice if booting on the second image.
Make sure a Sparrow Serial Radio is connected (see below how to program a Zolertia Zoul RE-MOTE as serial radio).
> cd products/sparrow-border-router
> make connect-full
If there are multiple nodes connected or the border router does not find the right device, the serial device to use can be specified using PORT.
> make connect-full PORT=/dev/tty.SLAB_USBtoUART
The Sparrow Serial Radio is used by the Sparrow Border Router to communicate with nodes over radio.
> cd products/sparrow-serial-radio
> make TARGET=zoul-sparrow BOARD=remote IMAGE=1
> make TARGET=zoul-sparrow BOARD=remote rescue-image
> make TARGET=zoul-sparrow BOARD=remote upload-rescue-image
NOTE: if you are using the firefly you need to make the image with
> make DEFINES=WITH_UART=1 TARGET=zoul-sparrow BOARD=firefly IMAGE=1
A serial-radio can be updated via the border router in the same way that nodes can be updated via OTA. Make sure a Sparrow Border Router is running and connected to a serial radio.
> cd products/sparrow-serial-radio
> make TARGET=zoul-sparrow BOARD=remote images INC=1
> make TARGET=zoul-sparrow BOARD=remote upload-local