tarts wireless sensors for raspberry pi · © 2015 tarts sensors. all rights reserved. 2 tarts...

Tarts Wireless Sensors

for Raspberry Pi For use with library v1.1

TM

TM

© 2015 Tarts Sensors. All Rights Reserved. 2 Tarts Wireless Sensors for Raspberry Pi (04/15)

Table of Contents Overview ................................................................................................................................................................................. 3

Use It For ............................................................................................................................................................................. 4

Preparation ............................................................................................................................................................................. 4

Community Forum .................................................................................................................................................................. 5

Serial Identification Numbers ................................................................................................................................................. 6

Antenna Orientation ............................................................................................................................................................... 6

Plate Communication .............................................................................................................................................................. 6

Light Indicators ........................................................................................................................................................................ 6

Pin Interface ............................................................................................................................................................................ 6

Setting up the software .......................................................................................................................................................... 7

Tips .......................................................................................................................................................................................... 7

Using Tarts Library .................................................................................................................................................................. 8

Insert Batteries ...................................................................................................................................................................... 15

Sample Code File Basic .......................................................................................................................................................... 16

RF Considerations ................................................................................................................................................................. 18

Position your Wireless Gateway in a central location .................................................................................................. 18

Position your Wireless Gateway Correctly .................................................................................................................... 18

Reduce wireless interference ....................................................................................................................................... 18

Antenna Orientation ..................................................................................................................................................... 18

Tech specs for this plate ....................................................................................................................................................... 21

Troubleshooting .................................................................................................................................................................... 21

Glossary ................................................................................................................................................................................. 22

Warranty Information ........................................................................................................................................................... 23

Limitation of Warranty and Remedies. ................................................................................................................................. 23

Certifications. ........................................................................................................................................................................ 23


TM

TM

Introduction

Overview The Tarts Gateway Plate for Raspberry Pi is an RF Transceiver that listens to RF communications from the TARTs line of battery powered, wireless sensors. Data from the sensors are captured in the plate and can be extracted to Raspberry Pi. Use the flexibility of customization offered by Raspberry Pi products to monitor your environment. DO NOT insert the batteries until the very last step. Everything else must be operating first, before batteries are inserted into the wireless sensors. DO NOT hot plug the plate onto the Raspberry Pi. Make sure everything is unpowered when attaching and removing the plate.

How Does It Work

1. Place sensors on things you want to monitor. 2. Tarts Gateway Plate for Raspberry Pi receives data beacons from sensors. 3. Compile a Code File to capture the data and route it wherever you want and do whatever you want with it.

What is a gateway? A gateway is a device used to connect two different networks. It transfers information from one realm to another. In this case, the sensor data is captured by the Tarts Gateway Plate and then delivered to the Raspberry Pi module. The sensor network is a star network, with the Tarts Gateway Plate being the point of contact for the sensors or wireless nodes. The nodes are battery powered and are asleep in between data transmissions. Periodically, they awaken, assess the environment for the parameter they are monitoring, package up the data in an RF packet, and beacon that RF packet. The Tarts Gateway Plate listens for RF packets coming in from the nodes. The Tarts Gateway Plate responds to the node. Having received the acknowledgement, the node returns to sleep mode until it is time to beacon again. The time in between beacons is referred to hereafter as report interval. All nodes have a report interval upon which they


report their state and data to the Tarts Gateway Plate. All sensors at factory have a default report interval of one minute, or 60 seconds. A variety of sensors are supported by the Tarts Gateway Plate. To name a few: Temperature, Humidity, Dry Contact, Water, Activity, PIR Motion, Tilt, and a various other voltage and current interface sensors. Depending on what the node is monitoring, depends on whether the node is considered a “trigger” sensor or an “interval” sensor. A trigger sensor is set up to allow the sleep mode to be interrupted upon qualification of an event. For example, a water sensor is designed to sleep between reports, but the presence of water interrupts the sleep mode and causes the node to immediately report the newly introduced presence of water. This type of node follows its report interval when there is no change in the detection of water. However, once water becomes present (or becomes absent), it ignores when it is due to report in again and instead immediately reports the change of state. The timer for the report interval starts over and the next data report will be when either: (1) the report interval elapses or (2) the absence of water is detected. An interval sensor just reports the data it collects on regular, predictable report interval. The sleep mode is never interrupted. An example of this type of sensor is the temperature sensor. This node sleeps for the duration of the report interval, then assesses the temperature, after which it reports that data to the Tarts Gateway Plate and resumes sleep until the report interval elapses, at which time it reports temperature data again. *Security section and Data sharing section * These devices are provided to allow easy access to sensor data in a low cost offering. To maintain flexibility of the system in various applications, no measures were taken to keep sensor data secure or restrict it in anyway. Please be aware that any Tarts Gateway Plate (Arduino, Raspberry Pi or others) can be configured to pick up sensor data or change sensor parameters, just by knowing the sensor identification number and sensor type. If an application requires that sensor data be secured, it is the responsibility of the user to address security issues and sharing restrictions. Tarts is not responsible for loss of data or devices due to hacking, sniffing, jamming, etc. How the user chooses to manage and route their data is controlled or influenced by its user(s).

Use It For

Home monitoring

Business monitoring

Restaurant monitoring

Elderly monitoring

Voltage/Current monitoring

Relay Control

Asset monitoring

Property monitoring

Preparation You will need:

1 or more wireless sensors (one plate can support up to 100 devices)

1 or more Tarts Gateway Plate(s) for Raspberry Pi

1 Raspberry Pi Platform (Model B, Model B+)

Viewing interface (monitor)

Communication cable for the Raspberry Pi to the viewing interface (S-Video or HDMI)

Ethernet cable

Antenna


Setup Procedure

Setup the Hardware Connect the Plate to the Raspberry Pi platform (unpowered)

Attach the antenna

Connect the Ethernet cable to your router

Straighten the antennas on your sensors. No batteries yet!

Connect the Plate to your viewing interface

Memorize or make note of your Gateway Serial ID number on the plate

Connect power Create and Compile the Software

Log into the platform (see page 7)

Raspberry Pi’s default and dedicated Serial Port Behavior inhibits the Tarts Gateway Plate from fully functioning. To address this issue, download this: https://github.com/lurch/rpi-serial-console. Tarts Examples http://www.tartssensors.com/libraries

Download libraries: o WiringPI. http://wiringpi.com/download-and-install o For Tarts: http://www.tartssensors.com/libraries/raspberrypi

Modify and Compile Program

Modify one or more of the examples provided with your gateway and sensor IDs.

Run “sudo chmod 777 build” and then run “sudo ./build all” to compile.

Run a program by typing “sudo ./Tarts”programName” (example: sudo ./TartsSniffer)

Set up the network

Wait for the gateway to indicate that it is Active (activity lights – page 6)

Put the batteries in the sensors (page 15) Note: If using a Raspberry Pi B+ board with 40 pin header, mount the Tarts gateway shield using the first 26 pins.

Community Forum Tarts provides access to the Tarts community with set up tips, support issues, and user applications. Please visit the forum at: www.tartssensors.com/community.

https://github.com/lurch/rpi-serial-console

http://www.tartssensors.com/libraries

http://wiringpi.com/download-and-install

http://www.tartssensors.com/libraries/raspberrypi

http://www.tartssensors.com/community


Setting Up the Hardware

Serial Identification Numbers Notice the serial identification number on the bar code sticker attached to the circuit board on each device (gateways and sensors). This is NOT the same as the UPC label on the packaging. It is on the face of the plate. You will need to know this identification number. The identification number is programmed into the unit at the time of manufacturing so it cannot be altered. Communications to and from the devices are identified by this number. For gateways, it is referred to as the Gateway Serial Identification Number. For sensors, it is referred to as Sensor Serial Identification Number. All references to the object use the Serial Identification Number. The number is generated on Base 36, using 0-9 and

A-Z. It’s data type is a character array.

Antenna Orientation Before proceeding further, take the time to straighten the antennas on your sensors. They will perform better if they are not curled up, but rather straight and vertical. For more antenna suggestions, see the RF Considerations section under the header titled: Other.

Plate Communication The Tarts Gateway Plate communicates with the Raspberry Pi platform via a standard UART interface.

Light Indicators The Tarts Gateway Plate has two lights that indicate it is functioning properly. Upon power up, the power light will turn green. When the gateway goes ACTIVE, the activity light will turn green. Sensor communication will cause the activity light to turn off and then back on.

Pin Interface

Left

Bottom Top

02 5V Power

04 5V Power

Ground 25

3V3 Power

10 GPIO 15 (RXD)

06 Ground

12 GPIO 18

08 GPIO 14 (TXD)

14 Ground

Ground 09

20 Ground

16 GPIO 23GPIO 22 15

GPIO 27 13

GPIO 17 11

18 GPIO 243V3 Power 17

GPIO 2 03

GPIO 4 07

GPIO 10 19

GPIO 9 21

GPIO 11 23 24 GPIO 8

26 GPIO 7

22 GPIO 25

Bottom TopP1-25 P1-26

P1-01 P1-02

GPIO 3 05

P1


Setting up the software

PI Tips When turning on your Raspberry Pi for the first time, there is a login required.

Default User Name: pi

Default Password: raspberry If you are experiencing issues getting your Raspberry Pi to run, see: http://www.raspberrypi.org/help/quick-start-guide/ To turn off your Raspberry Pi: send the command “sudo shutdown -h now” and wait for the module to shut completely down (like you would a computer). To reset your Raspberry Pi: send the command "sudo shutdown -r now". If you are having issues with your keyboard, visit our community forum for help.

Library Files Library files for the Tarts Raspberry Pi Plate can be downloaded from the website at http://www.tartssensors.com/libraries/raspberry-pi.

The library files download contains all of the files needed to get your project up and running as well as some sample programs that can be modified to meet your needs. The sample files are basic and do not by any means explore the vast possibilities of what can be done. These are our original ideas. Play with them and have fun creating your own. Feel free to share all your cool ideas with the community at www.tartssensors.com/community.

There is also a build script that will automatically compile and install all libraries and example applications to your Raspberry Pi.

http://www.tartssensors.com/libraries/raspberry-pi

http://www.tartssensors.com/community


Using Tarts Library For ease and simplicity, all behaviors for the wireless sensor network are handled in the Tarts Library files. The library was created to execute system processes while keeping the Code file options flexible and user friendly. Mainly, it minimizes the interaction needed to setup and maintain the gateway. It minimizes the work needed to access the data that the wireless sensor nodes are collecting and beaconing, as well as maintaining the sensors’ base code. The Tarts Library (Tarts.h) consists mainly of (a) the Tarts class and (b) a gateway object, (c) a sensor object, (d) a Sensor Message object.

Tarts Class

Becoming familiar with the Tarts class allows you to manage your wireless sensor network: register devices (gateways, sensors, etc), remove devices, find devices, and handle events occurring in the Tarts Gateway Plate. Everything you need to know about interacting with the class is described in this section. Creating a Tarts gateway: The gateway will need to be constructed. The gateway can be created by specifying just the gateway ID and the default addressing and pins are applied to create the gateway. Default addressing is 0x30, and the default pins are 5 and 6.

Type Function Call Description

static TartsCreate(const char* gatewayID) Create a gateway using the gatewayID

static TartsCreate(const char* gatewayID, uint_32 ChannelMask)

Create a gateway using the gateway ID and Channel Mask

Registering devices: Each device will need to be registered to the class in order to collect data from it. The Tarts Gateway Plate does not come with a foreknowledge of the devices in its network. Every Code file will need to include a command to register your network devices. This can be done by directly hard coding them in or by dynamically creating them on the fly. The object will need to be created first, before you can register it. Refer to the TartsGateway class for creating Tarts Gateway objects and refer to the Tarts Sensor classes for creating Tarts Sensor objects later on in this document. To register devices, use these methods:


bool RegisterGateway(TartsGateway gateway) // registers the gateway object.

bool RegisterSensor (const char* gatewayID, TartsTemperature sensor)

//registers a sensor to a gateway… the sensor object can be any sensor type; TartsTemperature is just an example

Notice that the sensors are linked to their gateways. We recommend registering sensors such that only one operating gateway is communicating with the sensor. In theory, you could register one sensor to multiple gateways, but we caution against doing this because the radio traffic gets messy with multiple gateways capable of talking to one sensor. Network instability, duplicate data, and wasted memory are just a few of the reasons we caution against this. There are situations where this can be useful, but these are advanced cases. So to keep the network clean, a sensor is registered to only one gateway. If you want to switch the sensor to another gateway, remove it or reform the network on that gateway, before registering it to another gateway. Removing devices: Should a device no longer be valid, you can remove it from the class. In order to remove any device successfully, it will have to have already been registered, or else the function does nothing. In other words, simply


creating the device does not register it to the class. So although it has been created, removing it can only happen after it has been registered. To remove devices, use these methods:


void RemoveGateway(const char* gatewayID)

// removes a registered gateway

void RemoveSensor(const char* sensorID) // removes sensor from ALL gateways* *The remove does not specify which gateway to remove the sensor from, so it will remove it from all gateways (plates) on the Raspberry Pi platform. You must register it back on the gateway desired after a RemoveSensor(ID) is performed.

Finding devices: If you know the serial identification number of a device in your network, the following methods return to you the associated object that has been created in the Tarts class. To find devices, use these methods:


TartsGateway* FindGateway(const char* gatewayID)

// returns the gateway object specified, if found

TartsSensorBase * FindSensor(const char* sensorID) // returns the sensor object specified, if found

Events: The Tarts class generates events when both the gateway and the sensors perform certain actions. Gateway Persist Event: this happens when (1) the gateway is powered up and activates successfully and (2) after a reform network has successfully been performed. The user can use this event to store key parts of the gateway in non-volatile (EEPROM, SD Card, data file) to be used to recreate the same network after reboot. (See TartsPersistence example code). This call back function will pass this parameter: const char* gatewayID. Gateway Message Event: this happens when the gateway delivers status messages. (See gateway states). This call back function will pass these parameters: const char* gatewayID, int stringID. Sensor Persist Event: this happens when any sensor is registered, or when a sensor has updated its configurations, or when the command to requestConfigurations() causes the sensor to send in its configuration page. The user can use this event to store key information from the sensor in non-volatile memory (EEPROM, SD Card, data file) to be used to recreate the same network after reboot. (See TartsPersistence example code). The call back function will pass this parameter: const char* sensorID. Sensor Message Event: this happens when any sensor delivers data to the gateway. The user uses this event to capture the data from the sensors. The call back function will pass this parameter: int error. Log Exception Event: Should an error occur, this will catch the error and report it to you for troubleshooting purposes. For example, if the class is able to identify a mismatch in the Gateway Serial Identification Number, it will report that to you. For more information on Exceptions, please see the Troubleshooting section later on in this document. To retrieve information from Events, include these calls in the setup() function of your program:


Void RegisterEvent_GatewayPersist(GatewayPersistEvent_t function) // call for the Gateway Persist event

void RegisterEvent_GatewayMessage(GatewayMessageEvent_t function) // call for the Gateway Message event

void RegisterEvent_SensorPersist(SensorPersistEvent_t function) // call for the Sensor Persist event

void RegisterEvent_SensorMessage(SensorMessageEvent_t function) // call for the Sensor Message event

void RegisterEvent_LogException(LogExceptionEvent_t function) // call for the Log Exception event


Process: The process method sets the gateway Active so it is ready to receive sensor data messages and perform its duties. It is recommended that your code file calls this method as often as possible. Use the Process() method in your Code file inside of the loop() function to interact with the Tarts Gateway Plate:


void Process() // Handles inbound messages to the gateway

void loop() {

Tarts.Process(); }

TartsGateway Object

Create a TartsGateway object in your Code file. You will need a gateway object for each plate. Before showing how to create the object, you will need to understand the parameters required for creation and what they mean. Parameters needed to construct the gateway:

Type Parameter Description

const char* Gateway Serial ID Number

Located on the bar code sticker on the Tarts Gateway Plate. Base 36 numeral system.

uint32_t Channel mask For advanced networks, the channel mask can be customized here. For basic networks, just use 0xFFFFFFFF.

Parameter definitions: Make a note of the Gateway Serial identification number on the bar code sticker on the back of the unit. It contains both numerals and alpha character. You will need to know this ID number. The Gateway Serial Identification number is programmed into the unit at the time of manufacturing so it cannot be altered. Communications to and from the gateway are identified by this number. The channel mask is a radio frequency parameter that allows the user to customize which channel(s) the radio is allowed to communicate on. Tarts supports 25 channels in the 900MHz, 5 channels in 868MHz, and 15 channels in 433MHz versions of product. For the purposes of a basic network, 0xFFFFFFFF tells the gateway that all available channels can be used for communication. Channels can be restricted by editing the bit number to zero. For example, if it is not desired that channel 5 be used, you will set bit 5 to zero. (Bits are ordered from least significant to most significant, so the bit farthest on the right is bit 0) Example: 0x00010A05 will only permit networks to be set up on channels 0, 2, 9, 11, and 16. The class supports declaring the gateway in dynamic memory.. This method will create the object and return the reference so the Tarts object can record it.

Example: //-In Raspberry Pi setup() Tarts.RegisterGateway(TartsGateway::Create(gatewayID,0xFFFFFFFF)); To access the TartsGateway object in your code file, create the object as follows below: TartsGateway* gateway = Tarts.FindGateway(gatewayID); The gateway may receive traffic from an unknown sensor. The user will know that an unknown sensor was identified by the gateway because it triggers a gateway message event. Perhaps the sensor was not registered to the Tarts class or perhaps the gateway does not recognize it. In such cases, the unknown sensor ID and sensor type is recorded by the


gateway in the event that the user wants to access it. To see an example of how it is accessed, see the TartsSniffer example code. To access the information for the last unknown sensor, use the functions below:


const char* getLastUnknownSensorID() Returns the sensor ID of the unknown sensor in the reported gateway message event

uint16_t getLastUnknownSensorType() Returns the sensor type of the unknown sensor in the reported gateway message events

Gateway states

As the gateway does its processing, there are a variety of states that it will pass through. Understanding the state that the gateway is currently in, will allow you to know what to expect. Overall, a gateway that is intercepting sensor data messages must be ACTIVE. If it is in any other state, it is not capturing sensor data messages. When working with the gateway, you will want to understand the state of operation that the gateway is currently in:

State Description

UNINITIALIZED Gateway object is created in software but the actual hardware has not initialized.

OFF Gateway has an error; should only remain in this state for 5 seconds total, and then try again to come back up.

INITIALIZED The object is created in the class and the IO pins for I2C communication have been set.

STARTING First communication to the gateway is successful. Checking on to do items…

REFORMING Restructuring the Wireless network. This includes resetting the radio channel, network and other parameters, as well as purging the current sensor list and rewriting it.

REMOVING This is performing the remove command and deleting devices.

LOADING Adding devices to prepare the radio to listen to them.

ACTIVATING Preparing to go ACTIVE.

ACTIVE Ready and listening for sensor communication.

Once the gateway has gone ACTIVE, a gateway persistence event will occur. Once registered, you can interact with the gateway using functions to obtain information from it. Use these functions for informational requests:


const char* getGatewayID() //Returns the identification number of the Tarts Gateway Plate

uint32_t getChannelMask() //Returns the Channel Mask parameter – the radio channel selector GatewayState getState() // Returns the state the gateway is currently in

uint8_t getOperatingChannel() // Returns the current radio channel that the gateway is communicating on with the sensors

The operating channel is the radio frequency channel currently in use. When powered up, the gateway selects a channel on which to set up the wireless network. It is this channel that the gateway will communicate on until it is forced to change channels via Reform Network request. One command is available to you for maintaining the gateway. It is the Reform Network command. It can be sent with no parameter and the gateway will restructure the wireless network. Or you can send in the new channel mask as a parameter. Either way, the gateway will find a new channel to operate on, reset internal network identifiers, and purge


its current sensor list (NOTICE** This will remove ALL sensors from the gateway; after a reform network command, sensors will need to be reregistered). Use this function to reform the wireless network:


void reformNetwork(); // Restructures the Wireless network. This includes resetting the radio channel, network and other parameters, as well as purging the current sensor list.

void reformNetwork(uint32_t newMask); // Restructures the Wireless network this time setting the channel mask to manage channel selection by the radio

After the successful execution of reformNetwork(), the gateway persistence event will be called. To access the TartsGateway object in your code file, create the object as follows below:

TartsGateway* gateway = Tarts.FindGateway(gatewayID); To access the functions available in the gateway object, use the syntax below:

uint8_t channel = gateway->getOperatingChannel();

Tarts Sensor Type Objects

If you have taken a peek into the library classes, you will find the TartsSensorBase class. This object holds values common to all sensors; however you cannot create an object from the TartsSensorBase because it is abstract; it must be inherited. The Tarts class takes care of all that for you. Each sensor comes with a pre-programmed sensor identification number, available to you on the bar code sticker on the back. Since it is programmed in at the time of manufacturing, it cannot be changed. This is how the sensor will be identified in the functions that create, register, modify or delete sensors. Also each sensor has a sensor type that identifies whether it is a temperature sensor, water detection sensor, activity sensor, etc. This is also programmed at the time of manufacturing and cannot be changed. When creating a sensor, register your sensor object by the class it belongs to.

Sensor Object Type Sensor Type Profile # Data Calibrate

TartsTemperature Temperature Sensor 2 Degrees Celsius Yes

TartsWaterTemperature Water Temperature Sensor 65 Degrees Celsius Yes

TartsHumidity Humidity Sensor 43 % RH Humidity, Degrees Celsius None

TartsDryContact Dry Contact Sensor 3 Closed (1); Open (0) None

TartsWaterDetect Water Detection Sensor 4 Present (1); Not Present (0) None

TartsWaterRope Water Rope Sensor 78 Present (1); Not Present (0) None

TartsOpenClose Open/Closed Sensor 9 Closed (1); Open(0) None

TartsButton Button Sensor 11 Not Pressed (0); Pressed(1) None

TartsAsset Asset Sensor 66 “ ”, Present None

TartsPassiveIR Passive IR Motion Sensor 23 No Motion (0); Motion (1) None

TartsActivity Activity Detection Sensor 5 No Motion (0); Motion (1) None

TartsVACDetect VAC Detection Sensor 64 Present (1); Not Present (0) None

TartsVDCDetect VDC Detection Sensor 71 Present (1); Not Present (0) None

TartsMeasure20mA Measure 0-20mA Sensor 22 Current in mA Yes

TartsMeasure1VDC Measure 0-1 VDC Sensor 1 Voltage in volts Yes





TartsMeasure500VAC Measure 0-500 VAC Sensor 32 Voltage in volts Yes

TartsResistance Resistance Sensor 70 Resistance in Ohms Yes

TartsTilt Tilt Sensor 75 Angle in Degrees None

TartsCompass Compass Sensor 28 Direction in Degrees Yes

TartsBasicControl Single Control Device 76 State of Switch (open or closed) None

To create and register a sensor, use the code below.

Example: //-In Raspberry Pi setup() Tarts.RegisterSensor(TartsTemperature::Create(sensor ID)); To access the sensor in your code file elsewhere, use the following: TartsSensorBase* sensor = Tarts.FindSensor(sensorID); Each sensor has configurations saved to it that depict its behavior. These configurations are: Report Interval: Amount of time that elapses in between sensor readings (sensor data messages). The default report interval is 60 seconds, or 1 minute. Link Interval: The sensors require that the gateway responds to their communications. Should a gateway fail to respond to a sensor for several consecutive attempts, the sensor will enter link mode. Link mode is also entered on power up. When the sensor is in link mode, no measurements are being taken on sensor data. The sensor’s primary focus is to find a gateway to talk to and save power. The Link Interval is the amount of time between attempts to find a gateway. The default is 10 minutes. This means that once every 10 minutes, the sensor attempts to find a gateway to talk to. Retry Count: The number of additional attempts made should the sensor get no response on its initial attempt to send data to the gateway before giving up. If the sensor gives up, that data point is lost. The default setting is 2. Valid settings are 0 – 10 inclusively. 0 means no retries are attempted on radio failures. Recovery: The number of consecutive report intervals that may fail to get a response from the gateway before the sensor leaves application mode and enters link mode. The default setting is 2. Valid settings are 0 – 10 inclusively. 0 means that the sensor will never fail out and change channels to look for a new gateway without power cycling the battery on the sensor. If you reform a gateway’s network, a sensor will not come back on its own without user intervention. If you would like to query the sensor to obtain these settings, use the functions that request this information. To request information from a sensor use the Sensor ID on the device:


const char* getSensorID() // Returns the sensor’s identification number printed on its label

TartsSensorTypes getSensorType() // Returns the sensor type, ie Temperature, Water Detection, etc

uint16_t getReportInterval() // Returns the report interval on the sensor

uint8_t getLinkInterval() // Returns the link interval on the sensor

uint8_t getRetryCount() // Returns the retry count setting on the sensor

uint8_t getRecovery() // Returns the recovery setting on the sensor

Should it be desired to change default parameters on any given sensor, the functions below will allow modification of those parameters. To modify the generic sensor parameters, use the functions below:



bool setReportInterval(uint16_t reportInterval) // change the report interval to a new value; measured in seconds

bool setLinkInterval(uint8_t linkInterval) // change the link interval to a new value; <18 value is in HOURS; >100 value is in MINUTES-100; ==0, default of 2 Hours is set

bool setRetryCount(uint16_t retryCount) // change the number of retries programmed to the sensor

bool setRecovery(uint16_t recovery) // change the recovery number programmed to the sensor

After the successful execution of one of the above modifying functions, a sensor persistence event will occur. Please note that this will take place on the next sensor report interval. Sensor actions include asking the sensor for its configurations and determining if there are pending messages for the sensor. To utilize the sensor actions, use the functions below:

Return Type Function Call Description

void requestConfigurations() Sets a flag on the gateway to obtain the sensor configurations from the sensor

bool pendingActions() Returns true if there is a message pending for the sensor and false if not.

The analog sensor types can be calibrated. To calibrate, call the calibrate routine and pass in the argument of calibration. To restore the sensor to its original defaults, call the restoreCalibrationDefault() method. To calibrate an analog sensor, use the functions below:


void calibrate(argument) //pass in the desired data value, wait 2 heartbeats to verify

void restoreDefaultCalibration() //undo the calibration settings and restore the sensor back to default

All the calibration arguments are floats, except for TartsCompass, which is an (int). The TartsCompass can only accept 0 (for North), 90 (for East), 180 (for South), 270 (for West).

Sensor Message Object

When a sensor records a data point, it will communicate that data point via radio frequency to the gateway. This will cause a Sensor Message Event to occur. In the function of the sensor message event will be the sensor identification number, received signal strength (RSSI), battery voltage, and a list of Datum objects. The Datum object is where the data from the sensors can be found and extracted. Extracted data will tell you the data name, the value of the data as collected by the sensor (raw data), and data that has been formatted for you. All of these parameters are strings. See the TartsBasic example code in the next section for how to use the Datum object in a Sensor Message Event.


Some examples of the data in the Datum are in the table below:

Sensor Type Name Raw Value FormattedValue

Temperature TEMPERATURE 236 23.6 C

Water Temperature TEMPERATURE 236 23.6 C

Humidity RH / TEMPERATURE 3455 / 25O1 34.55% 25.01 C

Dry Contact CONTACT 0 or 1 OPEN or CLOSED

Water Detection DETECT 0 or 1 NOT PRESENT or PRESENT

Water Rope DETECT 0 or 1 NOT PRESENT or PRESENT

Open Close CONTACT 0 or 1 OPEN or CLOSED

Button BUTTON 0 or 1 NOT PRESSED or PRESSED

Asset ASSET PRESENT

Passive IR PIR 0 or 1 NO MOTION or MOTION

Activity ACTIVITY 0 or 1 NO MOTION or MOTION

VAC Detection DETECT 0 or 1 NOT PRESENT or PRESENT

VDC Detection DETECT 0 or 1 NOT PRESENT or PRESENT

Measure 0-20mA CURRENT 565 5.65 mA

Measure 0-1 VDC VOLTAGE 1005 1.005 VDC



Measure 0-50 VDC VOLTAGE 12313 12.313VDC

Measure 0-500 VAC VOLTAGE 1106 110.6 VAC

Resistance RESISTANCE 8096 809.6 Ohms

Tilt PITCH / ROLL 9552 / 4226 95.52 DEG / 42.26 DEG

Compass HEADING 124 124 DEG

Basic Control SWITCH 0 or 1 OPEN or CLOSED

Strings

The Library includes a message string header file (TartsStrings.h). This is to make the readout more understandable.

However, it is not needed. You can save code space by not including the table in your code file.

Insert Batteries Once your Code file is running on the Raspberry Pi platform, the Activity light will be green. At this point, insert the batteries into the sensors, taking special care to orient the battery properly with the positive terminal face down.


Sample Code File - Basic #include "Tarts.h" #include "TartsStrings.h"

#define GATEWAY_ID ”T08KN4”

#define SENSOR_ID ”T08L10”

/********************************************************************************** *Global Variables *********************************************************************************/ int AppCalls = 0; //Keyboard Read Thread callback variable /********************************************************************************** *Tarts Events *********************************************************************************/ void onGatewayMessageEvent(const char* id, int stringID){ printf("TARTS-GWM[%u]-%d: %s\n", id, stringID, TartsGatewayStringTable[stringID]); if(stringID == 10) printf("ACTIVE - Channel: %d\n", Tarts.FindGateway(GATEWAY_ID)->getOperatingChannel()); } void onSensorMessageEvent(SensorMessage* msg){ char placeHolder[1]; if (msg->BatteryVoltage%100 < 10) placeHolder[0] = '0'; else placeHolder[0] = ''; printf("TARTS-SEN[%u]: RSSI: %d dBm, Battery Voltage: %d.%s%d VDC, Data: ", msg->ID;, msg->RSSI, msg->BatteryVoltage/100, placeHolder, msg->BatteryVoltage%100); for(int i=0; i<msg->DatumCount; i++){ if(i != 0) printf(" || "); printf("%s | %s | %s", msg->DatumList[i].Name,msg->DatumList[i].Value, msg->DatumList[i].FormattedValue); } printf("\n"); } /********************************************************************************** * Keyboard Thread and Arduino-like setup / loop code *********************************************************************************/ TARTS_THREAD(AppKeyboardReadThread){ char rxchar = 0; while(1){ std::cin >> rxchar; if(rxchar == 'q') AppCalls = 1; rxchar = 0; } return 0; //Here to keep the function happy } int setup() { printf("TARTs Basic application running..."); //Prepare all the call-back functions Tarts.RegisterEvent_GatewayMessage(onGatewayMessageEvent); Tarts.RegisterEvent_SensorMessage(onSensorMessageEvent); printf("All Event Handlers Registered.\n"); //Register Gateway if(!Tarts.RegisterGateway(TartsGateway::Create(GATEWAY_ID))){ printf("TARTs Gateway Registration Failed!\n"); return 1; } //Lastly Register All Sensors if(!Tarts.RegisterSensor(GATEWAY_ID, TartsTemperature::Create(SENSOR_ID))){ Tarts.RemoveGateway(GATEWAY_ID); printf("TARTs Sensor Registration Failed!\n"); return 2; }


if(TARTS_THREADSTART(AppKeyboardReadThread) != 0){ printf("Unable to start Keyboard Read Thread!"); Tarts.RemoveGateway(GATEWAY_ID); return 3; } printf("--Press q to exit--\n\n"); return 0; } void loop() { Tarts.Process(); if(AppCalls == 1){ AppCalls = 0; Tarts.RemoveGateway(GATEWAY_ID); exit(0); } } /********************************************************************************** * Execution entry point for this application *********************************************************************************/ //Main Application Loop int main(void){ if(setup() != 0) exit(1); while(1){ loop(); TARTS_DELAYMS(100);//Allow System Sleep to occur } }


Other

RF Considerations When dealing with wireless sensor networks, there are a lot of factors that affect the quality and reliability of transmission signals between your sensors and the gateway. We have compiled a list of useful tips to improve your wireless sensor network. Position your Wireless Gateway in a central location Position your Tarts Gateway in a central location within your facility. If the gateway is against an outside wall, the signal will be weak on the opposite side of your building. Position your Wireless Gateway Correctly Floors, walls and metal structures such as heating ducts and file cabinets, interfere with your sensor network's wireless signals. By avoiding these structural "Signal Killers" when placing your Tarts gateway and sensors, you can ensure optimal performance of your network. Reduce wireless interference If you have cordless phones or other wireless electronics in your facility, your gateway might not be able to "hear" your sensors over the noise from the other wireless devices. To quiet the noise, avoid wireless electronics that use the 900MHz frequency. Instead, look for cordless phones that use the 5.8GHz or 2.4GHz frequencies. Improve link speed When a sensor links to a gateway for the first time it begins searching at channel 0 and works its way up. It takes approximately one second to check a single channel, so a sensor linking with a gateway on channel 25 may take approximately 25 seconds to link. To improve link speeds with a gateway lower channels are preferable. Link only takes place when a sensor is powered up for the first time or if the sensor has lost connection with the gateway, this process does not occur every time the sensor communicates with the gateway. Once the channel has been established standard communications typically take less than a second.

Separation

The devices will need separation from each other for optimum performance. Where possible, allow a few feet between sensors. For gateways and sensors, allow at least 3 feet of distance, otherwise the RF link cannot be established.

Antenna Orientation

In order to get the best performance out of your Wireless Sensors, it is important to note proper antenna orientation and sensor positioning. Antennas should all be oriented in the same direction, pointing vertically out of the sensor. If the sensor is mounted flat on its back on a horizontal surface, you should bend the antenna as close to the sensor housing as possible giving you the most amount of antenna pointing vertical. You should make the antenna wire as straight as possible, avoiding any kinks and curving of the wire. For optimum signal strength determine the height at which the majority of your sensors will be mounted at and position the wireless gateway at the same height. The sensor signal strength will reduce if the sensors are positioned higher than the wireless gateway. Also sensors should be at least 3 feet away from each other and the wireless gateway to function properly.


Correct Antenna Orientation Antennas should all be pointing vertically and devices should be at least 3 feet apart.

Incorrect Antenna Orientation Antennas should not be pointing vertically and horizontally, and devices should not be closer than 3 feet.

DevicesAt Least 3 FeetApart

Horizontally Mounted

Ve

rtica

lly M

ou

nte

d

Ve

rtica

lly M

ou

nte

d

Horizontal Surface

Devices LessThan 3 FeetApart


Incorrect Sensor Positioning Sensors should not be mounted high with wireless gateways mounted low. Also, avoid positioning sensors or gateways on the floor.

So remember, when placing your wireless sensors, antenna orientation is critical to reliable performance of your

wireless sensors.

Reduced Signal Strength When Mounted At Different Heights


Tech specs for this plate Radio Bands available: 900 MHz, 868 MHz, 433 MHz (exclusive on each device)

Communication Interface: UART

Raspberry Pi Platform Compatibility: Model B, Model B+, Model A+

Dimensions: 1.375” x 2.125”

Power: 5V : 80mA

Antenna: Right Angle Whip, Gain: 3 dBi Connector: RPSMA

LED Indicators Activity and Power

Sensors Supported Up to 100 Tarts Wireless Sensors per Gateway Plate

Operating Temperature -40° to +85° C (-40° to +185° F)

Troubleshooting The Tarts Gateway Plate will turn off its wireless network after five network messages are queued up for delivery to the Raspberry Pi. Exception Errors:

ID MISMATCH – the gateway ID on the registered device does not match the gateway ID that the gateway is sending in its message. Fix the gateway ID or I2C address on the registration.

SENSOR TYPE MISMATCH – this means that data message coming from the sensor indicates that its sensory type (ie Temperature, Water Detection, PassiveIR, etc) was registered incorrectly at the time the sensor object was created.

Unregistered Sensor Detected – a sensor has submitted a request to join the network, but that sensor ID is not registered.

Communication from unregistered sensor – a sensor has submitted a data message that is not registered.

Startup Errors:

If the gateway repeatedly changes state from STARTING to OFF, then after 5 seconds STARTING to OFF again, The most likely reason for this is a hardware interface error.

o I2C addressing is not correct Reset or DataReady pins are not selected correctly.

Otherwise, there could be another hardware failure reason. Please check the forum or post in the forum.


Glossary Channel – one of several choices of specific radio frequency. Both the sensor and the gateway must be talking and listening on this specified frequency to communicate. UART – communication protocol between two electronic devices that uses signals to relay information back and forth

Interval sensor – a sensor that only ever reports on its report interval and never in between. IO Ports – Input / Output ports on electrical devices. Gateway – device used to connect two different networks. It transfers information from one realm to another. Gateway address – the physical connecting address between the Tarts Gateway Plate and the Raspberry Pi platform. Gateway serial Identification number – the printed number on the barcode label. Base 36 numeral system. Link interval – another mode of operation wherein the sensor’s sole priority is to find a gateway to communicate to. If a sensor cannot get a response from a gateway, it will abandon its report interval and switch over to link mode. No data is monitored in this mode. Message event – when a message is received from either a gateway or sensor. Persistence event – when a device completes an operation that may require saving or analyzing data within the properties of that device. Recovery – the number of consecutive report intervals allowed where a sensor does not receive a response from the gateway before the sensor switches into link mode, wherein no data is collected and the sensor’s sole priority is to find a gateway to communicate to. Report Interval – the amount of time that elapses in between data reports from the sensor. Retry count – number of times a sensor should continue to send the same RF data packet to the gateway, when it is not getting a response from the gateway. RF Packet – the unit of collected information that is sent wirelessly via radio frequency transmission. Star network – network of devices that consists of a central device (Tarts Gateway), to which all other nodes (Tarts sensors) are connected. The central device acts as a conduit to transmit the messages from the nodes. Trigger sensor – a sensor that allows sleep mode to be interrupted by a qualified event, regardless of its report interval.


Warranty Information (a) Tarts Sensors (Tarts) warrants that products will be free from defects in materials and workmanship for a period of one (1) year from the date of. Tarts will have no warranty obligation with respect to products subjected to abuse, misuse, negligence or accident. If any device firmware fails to conform to the warranty set forth in this section, Tarts shall provide a bug fix or firmware patch correcting such non-conformance within a reasonable period after Tarts receives from customer (i) notice of such non-conformance, and (ii) sufficient information regarding such non-conformance so as to permit Tarts to create such bug fix or software patch. If any hardware component of any product fails to conform to the warranty in this section, Tarts shall, at its option, refund the purchase price less any discounts, or repair or replace non-conforming products with conforming products or products having substantially identical form, fit, and function and deliver the repaired or replacement product to a carrier for land shipment to customer within a reasonable period after Tarts receives from customer (i) notice of such non-conformance, and (ii) the non-conforming product provided; however, if, in its opinion, Tarts cannot repair or replace on commercially reasonable terms it may choose to refund the purchase price. Repair parts and replacement products may be reconditioned or new. All replacement products and parts become the property of Tarts. Repaired or replacement products shall be subject to the warranty, if any remains, originally applicable to the product repaired or replaced. Customer must obtain from Tarts a Return material authorization number (RMA) prior to returning any products to Tarts. Products returned under this Warranty must be unmodified. Customer may return all products for repair or replacement due to defects in original materials and workmanship if Tarts is notified within ninety (90) days of customer’s receipt of the product. Tarts reserves the right to repair or replace products at its own and complete discretion. Customer must obtain from Tarts a Return material authorization number (RMA) prior to returning any products to Tarts. Products returned under this Warranty must be unmodified and in original packaging. Tarts reserves the right to refuse warranty repairs or replacements for any products that are damaged or not in original form. For products outside the ninety-day warranty period repair services are available at Tarts at standard labor rates for a period of one year from the customer’s original date of receipt. (b) As a condition to Tarts’s obligations under the immediately preceding paragraphs, customer shall return products to be examined and replaced to Tarts’s facilities, in shipping cartons which clearly display a valid RMA number provided by Tarts. Customer acknowledges that replacement products may be repaired, refurbished or tested and found to be complying. Customer shall bear the risk of loss for such return shipment and shall bear all shipping costs. Tarts shall deliver replacements for products determined by Tarts to be properly returned, shall bear the risk of loss and such costs of shipment of repaired products or replacements, and shall credit customer’s reasonable costs of shipping such returned products against future purchases. (c) Tarts’s sole obligation under the warranty described or set forth here shall be to repair or replace non-conforming products as set forth in the immediately preceding paragraph, or to refund the documented purchase price for non-conforming products to customer. Tarts’ warranty obligations shall run solely to customer, and Tarts shall have no obligation to customers of customer or other users of the products.

Limitation of Warranty and Remedies. THE WARRANTY SET FORTH HEREIN IS THE ONLY WARRANTY APPLICABLE TO PRODUCTS PURCHASED BY CUSTOMER. ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. TARTS’ LIABILITY WHETHER IN CONTRACT, IN TORT, UNDER ANY WARRANTY, IN NEGLIGENCE OR OTHERWISE SHALL NOT EXCEED THE PURCHASE PRICE PAID BY CUSTOMER FOR THE PRODUCT. UNDER NO CIRCUMSTANCES SHALL TARTS BE LIABLE FOR SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES. THE PRICE STATED FOR THE PRODUCTS IS A CONSIDERATION IN LIMITING TARTS’ LIABILITY. NO ACTION, REGARDLESS OF FORM, ARISING OUT OF THIS AGREEMENT MAY BE BROUGHT BY CUSTOMER MORE THAN ONE YEAR AFTER THE CAUSE OF ACTION HAS ACCRUED. IN ADDITION TO THE WARRANTIES DISCLAIMED ABOVE, TARTS SPECIFICALLY DISCLAIMS ANY AND ALL LIABILITY AND WARRANTIES, IMPLIED OR EXPRESSED, FOR USES REQUIRING FAIL-SAFE PERFORMANCE IN WHICH FAILURE OF A PRODUCT COULD LEAD TO DEATH, SERIOUS PERSONAL INJURY, OR SEVERE PHYSICAL OR ENVIRONMENTAL DAMAGE SUCH AS, BUT NOT LIMITED TO, LIFE SUPPORT OR MEDICAL DEVICES OR NUCLEAR APPLICATIONS. PRODUCTS ARE NOT DESIGNED FOR AND SHOULD NOT BE USED IN ANY OF THESE APPLICATIONS.


Certifications

United States FCC

This equipment has been tested and found to comply with the limits for a Class B digital devices, pursuant to Part 15 of the FCC Rules.

These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment

generates, uses, and can radiate radio frequency energy and, if not installed and used in accordance with the instruction manual,

may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a

particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by

turning the equipment off and on, the user is encouraged to try to correct the interference by one of more of the following measures:

• Reorient or relocate the receiving antenna

• Increase the separation between the equipment and receiver

• Connect the equipment into an outlet on a circuit different from that to which the receiver is connected.

• Consult the dealer or an experienced radio/TV technician for help.

Warning: Changes or modifications not expressly approved by Tarts could void

the user’s authority to operate the equipment.

RF Exposure

Tarts Wireless Devices Contain:

FCC ID: ZTL-RFSC1 This device has been designed to operate with an approved antenna listed below, and having a maximum gain of 5.1 dBi. Antennas not included in this list or having a gain greater than 5.1 dBi are strictly prohibited for use with this device. The required antenna impedance is 50 ohms. To reduce potential radio interference to other users, the antenna type and its gain should be so chosen that the equivalent isotropically radiated power (EIRP) is not more than that required for successful communication. Approved Antennas The following antennas are approved for use with Tarts devices.

• Hyperlink HG905RD-RSP (5.1 dBi Rubber Duck)

• Pulse W1063 (3.0 dBi Rubber Duck)

• ChangHong GSM-09 (2.0 dBi Rubber Duck)

• Specialized Manufacturing MC-ANT-20/4.0C (4” whip)


Certifications Continued

Canada (IC)

English

Under Industry Canada regulations, this radio transmitter may only operate using an antenna of a type and maximum (or lesser) gain approved for the transmitter by Industry Canada. To reduce potential radio interference to other users, the antenna type and its gain should be so chosen that the equivalent isotropically radiated power (e.i.r.p.) is not more than that necessary for successful communication. The radio transmitter (IC: 9794A-RFSC1) has been approved by Industry Canada to operate with the antenna types listed on previous page with the maximum permissible gain and required antenna impedance for each antenna type indicated. Antenna types not included in this list, having a gain greater than the maximum gain indicated for that type, are strictly prohibited for use with this device. This device complies with Industry Canada licence-exempt RSS standard(s). Operation is subject to the following two conditions: (1) this device may not cause interference, and (2) this device must accept any interference, including interference that may cause undesired operation of the device.

French

Conformément à la réglementation d’Industrie Canada, le présent émetteur radio peut fonctionner avec une antenne d’un type et d’un gain maximal (ou inférieur) approuvé pour l’émetteur par Industrie Canada. Dans le but de réduire les risques de brouillage radioélectrique à l’intention des autres utilisateurs, il faut choisir le type d’antenne et son gain de sorte que la puissance isotrope rayonnée équivalente (p.i.r.e.) ne dépasse pas l’intensité nécessaire à l’établissement d’une communication satisfaisante. Le présent émetteur radio (IC: 9794A-RFSC1) a été approuvé par Industrie Canada pour fonctionner avec les types d’antenne figurant sur la page précédente et ayant un gain admissible maximal et l’impédance requise pour chaque type d’antenne. Les types d’antenne non inclus dans cette liste, ou dont le gain est supérieur au gain maximal indiqué, sont strictement interdits pour l’exploitation de l’émetteur. Le présent appareil est conforme aux CNR d’Industrie Canada applicables aux appareils radio exempts de licence. L’exploitation est autorisée aux deux conditions suivantes : (1) l’appareil ne doit pas produire de brouillage, et (2) l’utilisateur de l’appareil doit accepter tout brouillage radioélectrique subi, méme si le brouillage est susceptible d’en compromettre le fonctionnement.

Additional Information and Support For additional information or more detailed instructions on how to use Tarts Wireless Sensors for Raspberry Pi, please visit us on the web at http://www.tartssensors.com.

Tarts Sensors

[email protected]

www.tartssensors.com

TM

TM

http://www.tartssensors.com/

mailto:[email protected]

tarts wireless sensors for raspberry pi · © 2015 tarts sensors. all rights reserved. 2 tarts...

Documents