Using third party sensors

This page reflects examples on how to use and implement compatible third party sensors.

What are third party sensors?

By third party sensors, we mean sensors that have been developed by others, with no affiliation to the Smart Citizen Team.

This page is a digest and updated version of the Making Sense D2.3 Smart Citizen Toolkit report and Making Sense D.24 Smart Citizen Toolkit report updates. Both these reports reflect information for the SCK 1.5, which is not a commercially available version of the kit. This guide is an update version for the SCK 2.1.

Use of already supported sensorsLink

The auxiliary port is designed to expand the sensor board by adding new sensors via the common I2C standard. However other protocols are supported, such as SPI or UART. The pins have the following default configuration:

PIN PORT Function
1 SCL I2C (by software: 1-WIRE or other)
2 SDA I2C (by software: 1-WIRE or other)
3 VCC Voltage
4 GND Ground

By connecting any of the supported sensors to the SCK, it will automatically be detected and data will be logged into the SD-card. You can check the output of the sensor command in the Serial output:

> sensor
Enabled
----------
Temperature (60 sec)
Humidity (60 sec)
Ext Temperature (60 sec)
Ext Humidity (60 sec)
Battery (60 sec)
Light (60 sec)
Noise dBA (60 sec)
Barometric pressure (60 sec)
PM 1.0 (60 sec)
PM 2.5 (60 sec)
PM 10.0 (60 sec)

Publishing data using custom devicesLink

The Smart Citizen Platform supports data from any sensor that has a numerical digital output. The Smart Citizen API supports other devices to publish data to the platform by previously agreeing with the Smart Citizen terms and conditions.

For each device type, a new device blueprint needs to be created. A device blueprint defines the sensors and the metrics that your devices will have. This will include the hardware details of your sensors and the kind of data that will be published to the platform. Custom calibration formulas to be applied to the data when processed in the platform can be also added.

How to do it?

Once a device blueprint is added to the platform, any user can create as many devices as needed and publish data to them following the standard Smart Citizen API. It is important to note that Device Blueprint currently cannot be created by users and should be requested by contacting support@smartcitizen.me.

The minimal Device Blueprint includes all the necessary data that a user might provide in order to create a Kit. It is composed of Components and those can reuse existing Sensors and Measurements definitions. Sensors define the hardware or software component that records the data. Measurements are descriptions of what sensors are recording. Blueprints can be shared across many devices or can be tailored per device in order to provide dedicated calibration formulas per individual sensor. This is achieved with the Components binding.

The following example shows a basic Device Blueprint in JSON. This is the minimum of information that a blueprint needs:

{
    name: The Frog,
    description: Custom Arduino Humidity Sensor,
    slug: ms:0,5,
    components: [{
        map: hum,
        equation: (125.0 / 65536.0 * x) + 7,
        sensor: {
            name: HPP828E031,
            description: Humidity,
            unit: %,
            measurement: {
                name: relative humidity,
                description: Relative humidity is a measure...
            }
        }
    }]
}

The following examples expand the previous Device Blueprint with the complete data model:

{
    “id”: 10,
    “uuid”: “056e452d-41c4-436d-a640-2157a278037d”,
    “slug”: “ms:0,5”,
    “name”: “The Frog”,
    “description”: “Custom Arduino Humidity Sensor”,
    “created_at”: “2016-06-18T16:25:02Z”,
    “updated_at”: “2016-06-18T16:25:02Z”,
    “components”: [{
        “id”: 35,
        “uuid”: “22da9377-5151-4547-a71b-6fd8958e1330”,
        “equation”: “(125.0 / 65536.0 * x) + 7”,
        “map”: “hum”,
        “sensor”: {
            “id”: 13,
            “uuid”: “1c19ae8f-b995-460f-87a3-a9d0c140abfb”,
            “parent_id”: 19,
            “name”: “HPP828E031”,
            “description”: “Humidity”,
            “unit”: “%”,
            “created_at”: “2015-02-02T18:24:30Z”,
            “updated_at”: “2015-07-05T19:54:54Z”,
            “measurement”: {
                “id”: 2,
                “uuid”: “9cbbd396-5bd3-44be-adc0-7ffba778072d”,
                “name”: “relative humidity”,
                “description”: “Relative humidity is a measure of the amount of
                moisture in the air relative to the total amount of moisture the    air    can    hold.  For instance,
                if the relative humidity was 50%, then the air is only half         saturated   with  moisture.”
            }
        }
    }]
}

Too much information?

Drop an email to support@smartcitizen.me and we will try to help!

Using SEEED Studio Grove bricks

You can use off-the-shelf sensors from the extensive Groove open hardware sensor library, removing the need to build our own sensor add-ons from scratch. Foto seeed sensors Seeed Grove Bricks

Implementing other sensorsLink

This is a WIP

This section is under heavy development. Thanks for your patience!

Implementation of other sensors goes through the modification of the Firmware. This is an advanced user feature, and previous programming experience in C++ is necessary.

The workflow we normally follow for this goes like:

  1. Find out if there is an already existing library for the desired sensor. Good places to look at are Adafruit's repository, Sparkfun's repository or a global Github search

  2. Implement this library in the firmware. The library needs certain functions to be valid. (More info soon!)

  3. If the device needs to log the data on the platform, you can email us at support@smartcitizen.me with a request for a new device blueprint. However, it is easier to simply log the data in SD-card in this case, if the online recording is not fully mandatory.

Contribute it back to the community

Make a pull request with your contribution back to the firmware so that other can use it!