SensorWeb docs draft

Contribute to SensorWeb.md

Contribute to SensorWeb

SensorWeb is still an early project, but we are looking forward to work with you, whoever is passionate about our vision, together to make it better.

Setup Your Sensors

Our goals is to build a crowdsourcing sensor network. We will definitely need your help to expand our device support, polish our software/documentations, and collect more sensor data.

Tell Us Where

If you want to have clearer picture of the air quality in your living environment, we are working on plans to deploy sensors and collect data. Tell us where you want to setup your sensors and we will get back to you when we have something for your region.

DIY Sensor Station

If you have basic knowledge of shell commands, and you're comfortable with wiring Arduino/Raspberry Pi, you can try to follow our sensor station setup guide for required hardware parts and setup instructions.

Contribute Code

If you are a developer/maker, the sensor station setup guide above should be easy for you. You can also help us polish our existing software/firmware or support more hardware boards/modules.

Contribute Project Ideas

The PM sensor network is just our very first step. We expect to see the world gets better by publishing and utilizing sensor data. If you see problems that can potentially be solved using the same technology, please don't hesitate to let us know.

Report Bugs

Wherever you found a bug in our code, UI, or contents, file a bug on bugzilla. If you don't have a bugzilla account in mozilla, create one here.

Find a Bug to Work on

Here is a list of bugs for SensorWeb. It might be hard to find a good first bug for you in early stages, but please do come back and have a look when you have time.

Getting Started Guide.md

Getting Started Guide

SensorWeb aims to pave the way for volunteers who is willing to solve real problems by exposing sensor data to the public. We don't just accept any random data, we encourage and help people work on shared vision together to achieve specific goals.

For instance, our first initiative is to build a crowdsourcing PM2.5 sensor network. With more data published, people would have better visibility of the air quality in their surroundings. So they can take actions accordingly.

Not everyone need to be a contributor. But if your do, tons of people would benifit from it.

Excited? Below are 4 steps to get you started.

Step 1: Create Your SensorWeb Account

Fill in the sign up form or just login with exsiting account. After logged in, a popup will tell you that you just joined PM2.5 initiative, since it's our only first initiative for now. Click OK will bring you to your dashboard.

Step 2: Create a Sensor ID and API Key

Click Add Device, fill in necessary information about your sensor and submit. You will see your sensor_id and api_key in the sensor detail page.

Step 3: Setup Your Sensor Station

Currently we provide some basic software to enable various ways to setup your sensor station. It might have frictions for non-developers for now. We will improve the setup process step by step, please stay tuned for upcoming releases.

A sensor station that integrates with our services should have:

• Sensors connected to it via IO headers/sockets to provide readings.
• Basic ability to process and (temporarily) store the data.
• Wired/Wireless internet connection to post to our REST API.

We listed 3 alternative ways below, you might already have some of the hardware parts, choose the one you comfortable with the most.

PC-based Sensor Station Setup

PC has sufficient computing power, storage, and internet connection, but to read data from sensors, we need USB adapters to connect to various kind of sockets/headers. Arduino could do the job in most cases, and for UART based sensors like some PM2.5 sensor, a simple and cheap (around $5) USB 2 TTL adapter would make it easy.

• Skills Required: PC software installation, command line interface, simple wiring.
• Hardware Requirement: PC or laptop, USB adapter, Sensors
• Instructions: See instructions on github

Arduino-based Sensor Station Setup

With internet-enabled Arduino-like boards, it's perfect for a sensor station setup since it supports various kind of sensors.

• Skills Required: PC software installation, command line interface, wiring Arduino
• Hardware Requirement: Arduino compatible board with the capability or module to connect to the internet, Sensors
• Instructions: See instructions on github

Raspberry Pi Sensor Station Setup

Raspberry Pi is a single board computer with IO pins, therefore it has the capability we need for a sensor station.

• Skills Required: command line interface, wiring Raspberry Pi
• Hardware Requirement: Raspberry Pi, SD Card, ethernet cable or wifi dongle, Sensors
• Instructions: See instructions on github

Using Other Hardware You Prefer

If you have other preferred hardware boards, you can build your own and have it send data to our service by calling our REST API.

Step 4: See Your Live Data

After setting up your sensor station properly, it should begin to send data to SensorWeb. Go back to the sensor detail page you just created in step 2, you'll see your data being visualized and updated in realtime.

SensorWeb REST API Reference.md

REST API Reference

Currently we only expose API for sensor devices to push data to SensorWeb.

Stay tuned for query APIs.

---

POST /sensors/sensor_id/data

After you logged in and created a sensor device, you can start to send data to SensorWeb with your api_key and sensor_id.

Request

POST http://api.sensorweb.io/sensors/{sensor_id}/data/

?api_key={api_key}&pm2_5={pm2.5_value}

Parameters

• sensor_id: Your sensor id, you can find it in your dashboard
• api_key: Your API key to access SensorWeb, you can find it in your dashboard
• pm2_5: PM sensor reading in µg/m³

Headers

Content-Type: application/x-www-form-urlencoded
Accept: application/json

Response

{
    "name": "My First PM2.5 Sensor",
    "description": "It's in my work place'",
    "address": "No. 106, Section 5, Xinyi Rd, Taipei City, Taiwan 110",
    "coordinates": "120.982025, 23.973875",
    "latest_update": {
      "datetime": "2013-08-25T17:10:00+00:00",
      "pm2_5": 11
    }
}

---

GET /sensors/

Find a list of sensors by coordinates and program ID.

Request

GET http://api.sensorweb.io/sensors/?api_key= {api_key}&program_id= {program_id}&coordinates= {coordinates}

Parameters

• api_key: Your API key to access SensorWeb, you can find it in your dashboard.
• program_id: Indicates what program the sensor belongs to.
• coordinates: GPS coordinates, latitude and longitude separated by comma.

Response

[
  {
    "sensorId": "xxxxxx",
    "name": "My First PM2.5 sensor",
    "description": "It's in my work place",
    "address": "No. 106, Section 5, Xinyi Rd, Taipei City, Taiwan 110",
    "coordinates": "120.982025, 23.973875",
    "latest_update": {
      "datetime": "2013-08-25T17:10:00+00:00",
      "pm2_5": 11
    }
  },
  {
    "sensorId": "xxxxxx",
    "name": "My Second PM2.5 sensor",
    "description": "It's in my backyard",
    "address": "No. 106, Section 5, Xinyi Rd, Taipei City, Taiwan 110",
    "coordinates": "120.982025, 23.973875",
    "latestUpdate": {
      "datetime": "2013-08-25T17:10:00+00:00",
      "pm25": 11
    }
  }
]

---

GET /sensors/sensor_id

Find a sensor by ID.

Request

GET http://api.sensorweb.io/sensors/{sensor_id}

Response

{
  "name": "pm2.5",
  "description": "It is about air quality",
  "address": "台北市信義區信義路五段106號",
  "coordinates": "120.982025, 23.973875",
  "currentState": {
    "pm25": 11
  }
}

---

GET /sensors/sensor_id/data

Get recent data being pushed to certain sensor.

Request

GET http://api.sensorweb.io/sensors/{sensor_id}/data

Response

[
  {
    "datetime": "2013-08-25T17:10:00+00:00",
    "pm25": 11
  },
  {
    "datetime": "2013-08-25T17:09:00+00:00",
    "pm25": 13
  },
  {
    "datetime": "2013-08-25T17:08:00+00:00",
    "pm25": 12
  }
 ]