User Tools

Site Tools


start

Getting Started

Mission

The Apitronics platform is designed to make deploying wireless networks outside easy. The stack abstracts communications, power, and sensor management, allowing you to focus on what sensors you want to use and what to do with the data.

The stack begins with wireless motes in rugged enclosures designed for the outdoors. We call this device the Bee.

The Bee communicates via radio modules to the Hive, which acts as a gateway device. When the Hive is plugged into your router, you can access the local browser interface as well as use different cloud services for off-site access and backup.

Bee

If you are interesting in expanding on the network by adding sensors, knowledge of Arduino/C++ is useful so that you can adapt drivers to work with the system. We'll make proven drivers available as we develop them, but since it is an open-source hardware project, others may be sharing drivers too!

Our wireless mote, the Bee, has the following features:

  • Low power consumption
  • Solar charger
  • A rugged enclosure and plug for outdoor deployment
  • SD card
  • Arduino, XBee, and GPS headers
  • Real-time calendar clock
  • Reliable NiMH battery

Setting up the IDE

You can download the Xmegaduino IDE with all our libraries included here (link coming soon).

Otherwise, if you want to have our libraries setup as a github repository so you can contribute and keep up with development, follow the instructions here.

On Linux, be sure to install openjdk-7-jre

Configuring XBees

Currently, we mainly support XBee 900HP modules for their incredible range ratings: 10kbps: up to 9 miles (15.5km), 200kbps: up to 4 miles (6.5km). There is the added benefit that they run at 900Mhz and not 2.4Ghz, which gives us less interference with WiFi and Bluetooth.

If for some reason you need to configure the XBees yourself, you can download X-CTU (Windows only). You can use these configuration files for XBee units - load them into X-CTU and write them onto your XBee units.

The important parameters are that you need put it in API Mode with Escape Characters for both Hive and Bee. For the Bee you need to enable PIN SLEEP and on the Hive make sure it's always awake.

Integration with Weather Underground

If you have an Apitronics weather station kit, it can integrate with Wunderground Personal Weather Station for personalized weather forecasts. To configure it:

  1. Register a new Personal Weather Station on Wunderground
  2. Edit an existing weather station bee
  3. Enter your weather station ID and Wunderground password (syncing should happen every 10 minutes)

Hive

If you want to manage where the data is going and what is being done with it beyond our browser capabilities, you can work with our code-base in Python or Node.js, or you can use whatever other language that runs on Linux!

Debian plus Daemons

The distribution included on the Hives is basically a small variant on the Debian distribution from Circuit Co. The script in the Hive directory called “install-dependencies.sh” sets everything up, including packages and configuration files.

Notably, it sets up several different servers and processes that help the Hive receive sensor readings via XBee and serve up web pages with your data.

We have several daemons managed by systemd:

  • hive-router.service
  • hive-redirect.service
  • hive-beekeeper.service
  • hive-honeycomb.service
  • hive-queen.service
  • hive-xbeepython.service

You can start and stop all of them at once by using the bash scripts, “start.sh” and “stop.sh”.

There are two cron jobs that you can see when you type: “crontab -l”:

  • a python scripts that tells CouchDB databases to compact themselves
  • a git pull from the Hive Updater repository so that you can find out if there are updates; updates will only launch if you click on Update Hive

CouchDB

CouchDB is being used for it's replication features and noSQL flexibility.

If CouchDB is running, you can easily explore the database by going to: hive.local:5984/_utils

From there, you will see all the databases. You should go here to read more about the basics of CouchDB if you are new to it.

The most interesting database for understanding how we're using CouchDB is the config database. It gets automatically populated with “default” Hive data by our install.js script; this includes many views that the app relies on and our first documents: sensor definitions!

Sensors Definitions

  • _id: FFFFFFFFFFFFFFFFFFFFFFFF00000001
  • _rev: 5-892041cc3a98fdee544749fb1bdbcb29
  • dataLength: 4
  • firmwareUUID: 0x00000001
  • kind: SensorDefinition
  • name: Battery Level
  • partRef: voltage divider
  • scalar: 0.01
  • shift: 0
  • units: V

This document defines what kind of sensor data is coming from. A well implemented Bee will tell the Hive what sensors it has before it starts streaming out datapoints and will do this by referring to the firmwareUUID. As you can see, the field is 32 bits wide which accommodates as many different firmware UUIDs as we will most likely ever need. This allows anybody to add a sensor easily as well!

The rest of this document will be explained in the context of parsing the packets later; just note that dataLength refers to bytes. Before going into more depth, we will look at how a Bee becomes a member of the Hive.

Bee Document

  • _id 811c182c8884d64cd961110a2f2961c2
  • _rev 1-6042744b42c4d35f09cf6d04edb5f329
  • address A92D0343FF4E
  • kind Bee
  • name North Field

The main thing that the Bee document provides is a unique address for the Bee; it can be its address as Zigbee device, it can be its (static) IP address, or it can be the SIM card number. The main thing that matter is that the address be unique and known when data is being transmitted from the Bee to the Hive.

Now we know enough to create which can be done by command line using curl:

 curl -XPOST hive.local:125/egg/new -H "Content-Type: Application/json" -d '{"sensors": ["0x1", "0x2", "0x3"],"address":"A92D0343FF4E"}'
 

What this comman did was create a new Bee with the same address as in the example. You'll also notice the sensors field which declares three sensors with firmware ID's 0x01, 0x02, 0x03; this is in reference to the sensor definition previously explained. It also means though, that three sensor instance documents were made which we'll talk about right now.

Sensors Instance

  • _id: 04781af2ef9b8ded840f34a3168e6aec
  • _rev: 1-84089f62373ca37aefcf878943542f7e
  • beeId: 811c182c8884d64cd961110a2f2961c2
  • kind: Sensor
  • order: 1
  • sensorDefinitionFirmwareUUID: 0x1

This is what the first sensor instance document from the example above would look like. First notice that the beeId refer to the _id of the Bee document above and that the sensorDefinitionFirmwareUUID refers to the sensor definition above as well. Note that not only has this document been created but we also now have a database called: sensor_04781af2ef9b8ded840f34a3168e6aec

Let's see how all this works now with a data packet.

Sending and Parsing a Data Packet

This where the data happens! Now we have awareness of a Bee with sensors attached to it, what those sensors are, etc.

Here's what the kind of data packet that the Hive expects:

 curl -XPOST http://hive.local:126 -H "Content-Type: Application/json" -d '{"address": "A92D0343FF4E", "data": {"10:45:15, 01/04/14": "3e0fab7d"}}'

What's going on here is that we have the right address that belongs to a Bee that the Hive is aware of. The Hive will then gather all the sensors from that Bee, in this case two, and it knows the order thanks to the order field in the sensor instance document. It will take “sensor instance where order is 1” first and then parse as many hex character as determined in the data length field of the firmware document. It will convert it from hex character to int and then scale it to a float and shift it and then put it in the sensor_04781af2ef9b8ded840f34a3168e6aec bucket, with UUID corresponding to epoch time in seconds.

Now we're putting data into the Hive!

start.txt · Last modified: 2014/08/27 13:38 by lthiery