sNET adapter to interface AirQ Networks devices with Arduino through AirQ ShielD
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
test/sNET_test
Device.cpp
Device.h
Message.cpp
Message.h
README.md
keywords.txt
sNET.cpp
sNET.h

README.md

sNET library for Arduino platform - ©AirQ Networks s.r.l. 2013

About

With the AirQ ShielD, this library allows an Arduino board to interact with AirQ Networks devices (wireless sensors and control boards). Thanks to this library, there is no need to know the underlying sNET protocol (sNET is the protocol used by AirQ Networks devices to exchange messages and it's described on the AirQ Networks technical wiki -- http://wiki.airqnetworks.com/index.php/SNET_Protocol).

Arduino communicates with the shield using SPI interface. Digital pins 9 and 2 of the Uno board are used for SSN and interrupt. However, library can be set up to use different pins if needed.

#Installation sNET library need to be installed before using it. First step is downloading the library from AirQ Networks github repository (http://github.com/airqnetworks). Next, open your Arduino sketchbook folder. If there is already a folder there called libraries, place the library folder in there. If not, create a folder called libraries in the sketchbook folder, and drop the library folder in there. Then re-start the Arduino IDE, and you should see your new library in the Sketch > Import Library menu. To download the library from this repository you can use one of the following ways:

  • Using git (preferred way.). Download the library using git. This will allow you to keep updated with the main repository every time a new release is pushed. To download the library, simply run the command:

     $ git clone https://github.com/airqnetworks/snet-arduino.git sNET

    and then copy the sNET folder into library subfolder of your sketchbook folder.

  • Downloading the zip. Click on the following link to download the whole library as a single zip file:

    https://github.com/airqnetworks/snet-arduino/archive/master.zip

##Requirements This library requires an AirQ ShielD. It was tested under Arduino IDE 1.5.x.

#How it works sNET library does a really simple task: it translates every message coming from a wireless device (sensor or control board) to a "high level" structure. Arduino programmers can use these structures to interact with devices. For each "physical" device (eg. an AirQ 310 control board) a corresponding device object is created (following the previous example, an object instance of the AIRQ310 object is created). Moreover, for each "message" generated by the device, a corresponding data message is created (AIRQ310DataMessage for the AirQ 310 control board.)

The following picture clearly shows how it works.

The picture shows this scenario: three AirQ 310 control boards are used; the AirQ ShielD on the Arduino Uno board collects messages coming from control boards. For each control board, the sNET library generates an AIRQ310 device object, and for each message the corresponding message is created.

sNET library was designed to minimize usage of both Arduino SRAM and flash memory. This means that:

  • There is no queuing mechanism of received messages in sNET. Only the last received message is available for a given device.
  • Programmers have to specify the number of remote devices on the same sensor networks that will interact with the shield (and so with the library).

The sNET class does the dirty job. Instances of this class are responsible to:

  • Generate instances of corresponding device objects for each detected wireless device;
  • Process messages generated on the SPI interface and update the corresponding device object.

Different from the previous release of the shield, the new AirQ ShielD 2.0 uses an interrupt driven approach to collect messages on the SPI interface. Programmers no long need to care about messages exchanged between AirQ ShielD and the end devices. This means, that the sNET::processMessages() method isn't available.

#Usage

Let's suppose we want to interface the three AirQ 310 control boards of the above picture. First, we have to instantiate a new sNET object, giving as argument the number of devices connected to the shield (and so, the number 3).

/* To use sNET library we have to include sNET.h in our sketch */
#include <sNET.h>
/* sNET lib uses SPI library. Arduino IDE requires that we include the header file here */
#include <SPI.h> 

Next, we have to call the sNET::begin() method. This method does all the required stuff to proper configure the library. The setup() function inside the main sketch is the best place to call it. sNET::begin() accept an integer: this number says to the library how many devices (sensors, control boards, etc) we are going to interface

void setup() {
  snet.begin(3);
}

Now, let's suppose that we want to turn on the RELAY1 of the second AirQ 310 board (the one with network address 4.0.1.2). sNET library allows to do this in a really simple way:

void loop() {
  AIRQ310 *board;

  /* We ask the sNET object to give us the reference the device object
   * corresponding to 4.0.1.2 board. The method sNET::getDeviceForDeviceID()
   * will return a pointer to an AIR310 object if the object was already created, 
   * otherwise it returns 0 (NULL). The device object is created as soon as sNET library
   * captures a message coming from that device */   
  if((board = (AIRQ310 *)snet.getDeviceForDeviceID(4,0,1,2)) != 0) {
     /* Ok, the AIRQ310 object was created and we can turn RELAY1 on */
     board->setRELAY1(ON);
     while(1); /* Job done. We can stop here */
  }
}

#Documentation More documentation and examples on how to use this library are available in AirQ Networks SDK Center at http://wiki.airqnetworks.com/index.php/SDK_Center.

#Licence

/**
 * Software License Agreement
 *
 * (C)Copyright 2013, AirQ Networks s.r.l. (http://www.airqnetworks.com)
 * All rights reserved.
 *
 * AirQ Networks licenses to you the right to use, modify, copy, and
 * distribute this software/library when used in conjunction with an 
 * AirQ Networks transceiver to interface AirQ Networks wireless devices
 * (transceivers, sensors, control boards and other devices produced 
 * by AirQ Networks). Other uses, either express or implied, are prohibited.
 *
 * THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT
 * WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT
 * LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL
 * AIRQ NETWORKS BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR
 * CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF
 * PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS
 * BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE
 * THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER
 * SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT
 * (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.
 *
 */