# TwinAIR: User guide

## Package content

The Package contains **three types of devices**:

1. **Sensor Pack #1 (indoor):** Carbon Dioxide (CO₂) and Formaldehyde (CH₂O)
2. **Sensor Pack #2 (indoor):** Electrochemical Sensors: Nitrogen dioxide (NO₂) and Ozone (O₃)
3. **Sensor Pack #2 (outdoor):** Electrochemical Sensors: Nitrogen dioxide (NO₂) and Ozone (O₃)

The image below shows the **indoor devices:**


And the **outdoor one**:


:::danger
**Important note**

* The Sensor Pack #1 (CO2+HCHO) sensors are **very sensitive to mechanical stress** and needs to be handled **very carefully**. Mishandling can lead to upsetting the calibration of the sensor.
:::

Below you can see the components:


:::info
In case of issues while collecting data, the device LED will likely show a weird behaviour (frozen in one color, for instance). For examples of normal behaviours, visit: https://docs.smartcitizen.me/Smart%20Citizen%20Kit/#operation-modes

You can reset the kit by inserting a pin or a small screw driver on the **Reset button** hole from the photos above.
:::

## Instructions

This guide details the necessary information and instructions for the devices configuration and deployment (both indoor and outdoor).

:::info
The guide provides the detailed steps for the users who want to register the devices by themselves. If you requested the registration process done by Fab Lab Barcellona, you can skip those steps.
:::

1. **Only for Sensor Pack #2 (NO2 + O3)**: This device comes with two blue round stickers on the blue side of the sensors, which are used as protective sheets to secure the sensors. Peel them before deployment


2. **All devices** come with the battery disconnected. Connect it to the female socket on the kit, near the USB connector. **Make sure it clicks** and that device turns on.

:::danger
**Important**
The device will not work **reliably** without the provided LiPo battery connected **permanently**.
:::

3. **All indoor devices**: These devices require USB cable and USB power plug, provided in the drawstring cloth bags. The cable needs to be passed through the hole indicated below. Connect the battery first, and then the USB cable.


4. **All devices**: Plug in the device to make sure it works before proceeding with its configuration or installation.
5. **All devices**: the devices are not configured by default, unless you have requested otherwise. For the configuration, please refer to the [device configuration section
](#device-configuration). If configured, proceed to the following step.
6. **Oudoor devices only**: An AC cable is provided (as per the image above). You can change this cable by opening the grey provided IP box, and change the cable on the screw connectors (more information on the [Power supply documentation](https://docs.smartcitizen.me/Components/boards/Power%20Supply/))


### Buttons

There are two buttons on the Device: the `on/off` button and the `reset` button:

The`ON/OFF` button is located here:


The `ON/OFF` button is used for:
- Turning OFF the device, by pressing 5s
- Turning ON the device, by clicking it (once)
- Doing a factory reset (generally not needed), by pressing 15s

:::info
If the device runs out of battery, you generally can simply plug it in. If the device's battery is completely drained, you will need to click the `ON/OFF` button after 5' of charging the battery.
:::

The `reset` button, is located here:


:::danger
You only need to use this button if to reset the device. It's the best option if you get a notification when the device stops publishing data.
:::

### LEDS

:::info
Check the LED colors in: https://docs.smartcitizen.me/Smart%20Citizen%20Kit/#operation-modes
:::

## Placement

There are **only** two possibilities for the device to placed: laterally or vertically.

:::danger
The device **should never be placed horizontally** (wide side flat on a surface). This placement would cover completely the sensor inlets, or leave them exposed to dust accumulation. Likewise, the sensors, do not work properly on this configuration.
:::



### Outdoor sensors

The outdoor sensors are deployed as below:


:::warning
Note the slots on the cover to pass zip-ties, screws or other elements to hold the device
:::

## Device configuration

**All devices**: visit the onboarding app at [start.smartcitizen.me](https://start.smartcitizen.me). The onboarding app at will guide through the process of configuring the device. **You will need to repeat the process for as many devices as you have.**

**Before you start** make sure you have:

- [ ] A computer to visit the onboarding app
- [ ] A smartphone (or tablet, or another computer) to connect to the device and configure it

:::info
Make sure that, if you register the device on your own, the device name is as provided in the table via email, with the following format:

`SITE_BUILDING_ROOM_#MAC`

As an example:

`ETR_MAIN_1_#DF81`

You can find this information in the provided materials via email.
:::

:::danger
**Always use the same user** for registering all TwinAIR devices.
:::

:::danger
**Do not change the name of the device** once it has been agreed with IAAC.
:::

### Enable notifications

The easiest way to enable notifications is to visit your device on [the website](https://smartcitizen.me/kits/<DEVICE-ID>) and click on the`EDIT button` on the bottom part of the graphs


Then, scroll down to the notifications section and enable both. This will trigger an email in case the device stops publishing.


:::danger
This step is crucial to ensure that, in the event of sensor malfunction, we can act as fast as possible to data loss. Since TwinAIR project relies heavily on this data, we encourage and appreciate if the pilot contact points can support on this matter.
:::

### Enable data forwarding to DMP

The easiest way to enable forwarding is to visit your device on [the website](https://smartcitizen.me/kits/<DEVICE-ID>) and click on the`EDIT button` on the bottom part of the graphs


Then, scroll down to the forwarding section and enable the checkbox. Make sure all the other settings are shown as in the image below:


:::danger
If you do not see this, please contact Fab Lab.
:::

### Handling calibration data

**Sensor Pack #2** requires handling of calibration data. For this reason, it's necessary to store the physical ID (`Station ID` or `Hardware ID`) of the unit alongside to the virtual device in the Smart Citizen Platform. The hardware ID should normally be in a sticker to the enclosure both inside and outside and looks like this:


**Station ID**

- This number is important to relate to the actual calibration values of the sensors, stored in the data repository. In order to postprocess the data and calculate pollutants, make sure that the `Station ID` is safely stored in the platform's device

:::danger
This hardware ID is not the same as the `device ID`. The `device ID` is the number you have after the smartcitizen.me/kits/ url where you see the data of your device. The `Station ID` is the one in the sticker. The `Station ID` is not meant to change, while the `device ID` can change as you can register your kit many times!
:::

- The easiest way to store this ID is to visit your device on [the website](https://smartcitizen.me/kits/<DEVICE-ID>) and click on the`EDIT button` on the bottom part of the graphs


- Then, in the `hardware URL` field, introduce the number in the sticker (it should be something like `SCAS2200XX`)


- Once this process is done, you should be able to check that the postprocessing is safely stored in the Platform by visiting the following link (Make sure your`<DEVICE-ID>` is correct): `https://api.smartcitizen.me/v0/devices/<DEVICE-ID>/`

After this, we will take care of processing the data in a periodic way.

## Additional information

### Battery Information

All devices comes with USB cable and an adapter with an additional 2000mAh LiPo battery. The SCK has a micro USB port and can be charged like any smartphone or tablet using a dedicated adapter or a computer USB port.

:::info
Battery characteristics can be found in the following link:
https://docs.smartcitizen.me/_FAQ/#what-batteries-are-shipped-with-the-kits
:::

### Data logging

**Wi-Fi Mode (online)**
This is the standard mode and requires a Wi-Fi connection. In this way, the device will publish data every minute (time resolution can be configured) on the smartcitizen.me platform. If a micro SD card is inserted, the data will be stored in duplicate as a backup.

:::info
The kit supports Wi-Fi WEP, WPA/WPA2 and open networks, those the standard Wi-Fi networks found in domestic and small businesses environments. However, it does not support WPA/WPA2 Enterprise networks such as EDUROAM or networks with captive portals such as those found in Airports and Hotels.
:::

**SD Mode (offline)**

If we do not have an internet connection, we can use the SD mode. In this case, the device will record the data on the micro SD card. Later we can read the card using a card reader. The recorded data can be visually explored in a spreadsheet but also published on the platform utilising the [UPLOAD CSV](https://docs.smartcitizen.me/Guides/getting%20started/Uploading%20SD%20Card%20Data/?h=csv) option.

**Limitations**
:::danger
While on SD-card mode, the device needs constant power (either USB or battery).
:::

- The Kit location needs to be set during the installation process, and it can be updated at any time using the EDIT option on the platform if you made a mistake. However, the Kit does not record its location automatically neither we can't have multiple locations for the same Kit in the platform.
- Unstable Wi-Fi environments need careful consideration. Check these guidelines for support: https://docs.smartcitizen.me/_FAQ/#what-can-i-do-in-unstable-wi-fi-environments