# MyAir Devices
This is the bluetooth interface document and specification on communicating with the myAir devices. They are nrf52832 devices and use the nordic semi tools.

## Terminology
| Term | Description |
|--------------------------------|----------------------------------------------------|
| MA `ma_` | MyAir (prefix) |
| MATSK `matsk_` | MyAir Task (prefix) |
| Packet | Data that will be send over BT. |
| Data frame | Combination of timestamp and data |
| Little/big endian (Endianness) | Byte order in which multi-byte numbers are stored. |
| |

_Release v2.17.0, SDK16.0.0, S132_

# Installing Segger embedded studio 🛠
Follow [this Youtube tutorial](https://www.youtube.com/watch?v=YZouRE_Ol8g) or follow the following steps:
- Go to [Segger Website](https://www.segger.com/products/development-tools/embedded-studio/)
- Install the IDE
- Download SDK 16.0.0 from [this link](https://www.nordicsemi.com/Software-and-Tools/Software/nRF5-SDK)
- Extract the SDK .zip

# Starting a project
- Go in the SDK folder
- Create a new folder inside the SDK16.0.0 folder (this guide calls it 'projects')
- Clone the repository 'your-project' in folder projects (in the SDK16.0.0).
- Go to `your-project`->sdk->nrf52832->`your-project`.emproject
- Make sure that the softdevice is uploaded on the microcontroller.
- If the softdevice has not been uploaded yet, or the wrong one has been uploaded. Go to paragraph "Uploading S132 softdevice" first.
- Otherwise, build the project. Go to label "Build" and press "Build MyAir-embedded-ble" or press F7.
- Now it should work(not give an error).

# Installing S132 SoftDevice
- Install nRF Connect. Follow [this link](https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Connect-for-desktop/Download#infotabs). _(v3.3.2 at time of writing)_
- Open the NRF Connect app.
- Install the 'Programmer' tool.
- Turn on the sensor and connect it to the J-Link debugger.
- It should automatically start reading your device. If not, press 'Read' on the right side of your window.
- On the right top corner, press 'Add HEX files', press 'Browse...' and go to your SDK16.0.0 folder. In your folder, go to components>softdevice>s132>hex and select `s132_nrf52_7.0.1_softdevice.hex`.
- On the right side, press 'Erase & Write'. This should take a few seconds.
- Now your screen should look like this. <br>

# Installing CMSIS configuration wizard
- The system is very generic and changing it can easily be done using a GUI called CMSIS configuration wizard
- This tool is both used to change `ma_config.h` for myAir related settings as well as `sdk_config.h` for NRF related changes (Be careful with what you modify, this could break the system).
- To install this tool follow [this YouTube guide](https://www.youtube.com/watch?v=b0MxWaAjMco)
- To apply the gui to newly added constants to the to ma_config.h the [CMSIS syntax](https://www.keil.com/pack/doc/CMSIS/Pack/html/configWizard.html) can be used in comments.

# Configurations

## Select sensor profile

MyAir supports many different sensors and configurations. To select which sensor is connected, MyAir uses sensor profiles. These profiles tell the software about how to collect data and handle the data and what (default) metadata to use. You can read more about this in [MyAir profiles](https://github.com/VTECadmin/myAir-embedded-ble/wiki/MyAir-profiles). It is important that you select the right profile. To select a profile, open `ma_config.h` with the CMSIS configuration wizard, go to the folder 'MyAir data configuration' and press 'MyAir profiles' (if you use 2.13.1 or earlier this is called 'Memory profiles'). There you can select your sensor profile.


## Enable the logs
MyAir has custom logs which tell you about the state of the system print things like sensor values. These are disabled by default. To enable the logs, open `ma_config.h` in the CMSIS configuration wizard and in the folder 'Log configuration' pres 'MyAir log severity level'. There you can enable the logs and set the severity. If you want to see where the log came from (line number, file name and function name) you can select this with 'MyAir log prefix'.

# MyAir BLE interface

The ADV values broadcasted will always be in little endian (where the byte orders are reversed) and thus has to be translated to get original value.

| Property | Value | Fixed |
|-------------|----------------------------------------|-------|
| Name | `MAFD0000` | No |
| Mac address | `FF:45:33:22:11:CD` | No |
| UUID | `1A310293-63B2-0795-204F-1DDA0100D29D` | Yes |

- Base UUID: `1A31xxxx-63B2-0795-204F-1DDA0100D29D`
- Shown as: `1A310000-63B2-0795-204F-1DDA0100D29D`

*In code:*

{0x9D, 0xD2, 0x0, 0x1, 0xDA, 0x1D, 0x4F, 0x20, 0x95, 0x7, 0xB2, 0x63, 0x00, 0x00, 0x31, 0x1A}

## UUID table

The UUID will be build from the Base UUID, with in the Short-ID section the Profile ID and service ID.
This can be shown as `1A31ppss-63B2-0795-204F-1DDA0100D29D` where `p` stands for Profile ID and `s` stands for service ID.
For profiles look at [MyAir profiles](https://github.com/VTECadmin/myAir-embedded-ble/wiki/MyAir-profiles) wiki page. For services look at [BLE services](https://github.com/VTECadmin/myAir-embedded-ble/wiki/BLE-services) wiki page.

### Broadcast UUID

| UUID | Profile ID |Profiles |
|----------------------------------------|------------|---------------------------|
| `1A310101-63B2-0795-204F-1DDA0100D29D` | `0x01` | Portable Profile Finedust |
| `1A310201-63B2-0795-204F-1DDA0100D29D` | `0x02` | Portable Profile CO2 |
| `1A310301-63B2-0795-204F-1DDA0100D29D` | `0x03` | Portable Profile NH3 |
| `1A310401-63B2-0795-204F-1DDA0100D29D` | `0x04` | Fixed profile Finedust |
| `1A310501-63B2-0795-204F-1DDA0100D29D` | `0x05` | Fixed profile CO2 |
| `1A310601-63B2-0795-204F-1DDA0100D29D` | `0x06` | Fixed profile NH3 |

### Task UUID

| UUID | Profile ID |Profiles |
|----------------------------------------|------------|---------------------------|
| `1A310102-63B2-0795-204F-1DDA0100D29D` | `0x01` | Portable Profile Finedust |
| `1A310202-63B2-0795-204F-1DDA0100D29D` | `0x02` | Portable Profile CO2 |
| `1A310302-63B2-0795-204F-1DDA0100D29D` | `0x03` | Portable Profile NH3 |
| `1A310402-63B2-0795-204F-1DDA0100D29D` | `0x04` | Fixed profile Finedust |
| `1A310502-63B2-0795-204F-1DDA0100D29D` | `0x05` | Fixed profile CO2 |
| `1A310602-63B2-0795-204F-1DDA0100D29D` | `0x06` | Fixed profile NH3 |

## Data frames

### Advertisement/Broadcast data-frame
_Release v2.13.0, SDK16.0.0, S132_

Format of Advertisement Data(AD) is shown here and will always follow `[AD Length][AD type][AD value]`. Default values are shown here as well.
For data type reference: [AD data type](https://www.bluetooth.com/specifications/assigned-numbers/generic-access-profile)

| Data | Element | Size | Type |
|-------------------------------------------------------|---------|------|------|
| AD length: [0x02] | 0 | 1 | BLE |
| AD type: [0x01] - A Flag | 1 | 1 | BLE |
| AD value: [0x06]- The device is BLE only | 2 | 1 | BLE |
| AD length: [0x11] | 3 | 1 | UUID |
| AD type: [0x07] - Complete 128-bit UUID | 4 | 1 | UUID |
| AD value: 128-bit UUID (`1A310001-63B2-0795-204F-1DDA0100D29D`) | 5-20 | 16 | UUID |
| AD length: [0x06] | 21 | 1 | Name |
| AD type: [0x09]Complete Device name | 22 | 1 | Name |
| AD value: [Default: `MA000`] | 23-27 | 5 | Name |

### Scan response data frame
_Look at the wiki page [MyAir profiles](https://github.com/VTECadmin/myAir-embedded-ble/wiki/MyAir-profiles)_

***
_Release v2.14.0, SDK16.0.0, S132_

# BLE Service information

| Name | Service ID | Type |
|-----------|-------------|-------------|
| Default | `0x00` | Reserved |
| Broadcast | `0x01` | Advertising |
| Task | `0x02` | Service |

_Look at issue 'P2P connection in BLE' ([#157](https://github.com/VTECadmin/myAir-embedded-ble/issues/157))_

*Updated release v2.17.0* <br/>
This document will contain the settings for different profiles of MyAir. <br>

# Profiles [BLE Broadcast]

## Portable Finedust

### Sensors
- PMS5003 [Finedust]
- BME280 [Temperature, Humidity, Pressure]
- Battery Voltage
- Charge state [Status register]

### Default properties
| Property | Value |Fixed |
|-------------|----------------------|-------|
| Name | `MAFD0000` | No |
| Mac address | `FF:45:33:22:11:CD` | No |
| Profile ID | `0x01` | Yes |

### Broadcast
| Data | Element | Size | Type | Data Type | Factor |
|-------------------------------------|---------|------|---------|-----------|--------|
| Manufacturer specific size(0x1D) | 0 | 1 | Company | `uint8` | - |
| AD type manufacturer specific(0xFF) | 1 | 1 | Company | `uint8` | - |
| Company ID(tbd, 0xFF) | 2-3 | 2 | Company | `uint16` | - |
| Temperature (°C) | 4-5 | 2 | MyAir | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | MyAir | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | MyAir | `uint16` | - |
| Battery voltage (mV) | 10 | 1 | MyAir | `uint8` | `/20` |
| Status register | 11 | 1 | MyAir | `uint8` | - |
| PM 1.0 | 12-13 | 2 | MyAir | `uint16` | - |
| PM 2.5 | 14-15 | 2 | MyAir | `uint16` | - |
| PM 10 | 16-17 | 2 | MyAir | `uint16` | - |
| PC 0.3 | 18-19 | 2 | MyAir | `uint16` | - |
| PC 0.5 | 20-21 | 2 | MyAir | `uint16` | - |
| PC 1.0 | 22-23 | 2 | MyAir | `uint16` | - |
| PC 2.5 | 24-25 | 2 | MyAir | `uint16` | - |
| PC 5.0 | 26-27 | 2 | MyAir | `uint16` | - |
| PC 10 | 28-29 | 2 | MyAir | `uint16` | - |

### Memory data
| Data | Element | Size | Data Type | Factor |
|-------------------------------------|---------|------|-----------|--------|
| Timestamp (epoch) | 0-3 | 4 | `uint32` | |
| Temperature (°C) | 4-5 | 2 | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | `uint16` | - |
| Battery voltage (mV) | 10 | 1 | `uint8` | `/20` |
| PM 1.0 | 11-12 | 2 | `uint16` | - |
| PM 2.5 | 13-14 | 2 | `uint16` | - |
| PM 10 | 15-16 | 2 | `uint16` | - |
| PC 0.3 | 17-17 | 2 | `uint16` | - |
| PC 0.5 | 19-20 | 2 | `uint16` | - |
| PC 1.0 | 21-22 | 2 | `uint16` | - |
| PC 2.5 | 23-24 | 2 | `uint16` | - |
| PC 5.0 | 25-26 | 2 | `uint16` | - |
| PC 10 | 27-28 | 2 | `uint16` | - |

Frame size = 29
Max frames per packet = 8

## Portable CO2

### Sensors
- TDE5514 [CO2]
- BME280 [Temperature, Humidity, Pressure]
- Battery Voltage
- Charge state [Status register]

### Default properties
| Property | Value |Fixed |
|-------------|----------------------|-------|
| Name | `MACO2000` | No |
| Mac address | `FF:46:33:22:11:CD` | No |
| Profile ID | `0x02` | Yes |

### Broadcast
| Data | Element | Size | Type | Data Type | Factor |
|-------------------------------------|---------|------|---------|-----------|--------|
| Manufacturer specific size(0x1D) | 0 | 1 | Company | `uint8` | - |
| AD type manufacturer specific(0xFF) | 1 | 1 | Company | `uint8` | - |
| Company ID(tbd, 0xFF) | 2-3 | 2 | Company | `uint16` | - |
| Temperature (°C) | 4-5 | 2 | MyAir | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | MyAir | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | MyAir | `uint16` | - |
| Battery voltage (mV) | 10 | 1 | MyAir | `uint8` | `/20` |
| Status register | 11 | 1 | MyAir | `uint8` | - |
| CO2 (ppm) | 12-13 | 2 | MyAir | `int16` | - |

### Memory data
| Data | Element | Size | Data Type | Factor |
|-------------------------------------|---------|------|-----------|--------|
| Timestamp (epoch) | 0-3 | 4 | `uint32` | |
| Temperature (°C) | 4-5 | 2 | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | `uint16` | - |
| Battery voltage (mV) | 10 | 1 | `uint8` | `/20` |
| CO2 (ppm) | 11-12 | 2 | `int16` | - |

Frame size = 13
Max frames per packet = 19

## Portable NH3 🐮
**Not working in current release `v2.17.0`**
### Sensors
- ? [NH3]
- BME280 [Temperature, Humidity, Pressure]
- Battery Voltage
- Charge state [Status register]

### Default properties
| Property | Value |Fixed |
|-------------|----------------------|-------|
| Name | `MANH3000` | No |
| Mac address | `FF:47:33:22:11:CD` | No |
| Profile ID | `0x03` | Yes |

### Broadcast

| Data | Element | Size | Type | Data Type | Factor |
|-------------------------------------|---------|------|---------|-----------|--------|
| Manufacturer specific size(0x1D) | 0 | 1 | Company | `uint8` | - |
| AD type manufacturer specific(0xFF) | 1 | 1 | Company | `uint8` | - |
| Company ID(tbd, 0xFF) | 2-3 | 2 | Company | `uint16` | - |
| Temperature (°C) | 4-5 | 2 | MyAir | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | MyAir | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | MyAir | `uint16` | - |
| Battery voltage (mV) | 10 | 1 | MyAir | `uint8` | `/20` |
| Status register | 11 | 1 | MyAir | `uint8` | - |
| NH3 (?) | 12 | 1 | MyAir | `uint8` | - |

### Memory data
| Data | Element | Size | Data Type | Factor |
|-------------------------------------|---------|------|-----------|--------|
| Timestamp (epoch) | 0-3 | 4 | `uint32` | |
| Temperature (°C) | 4-5 | 2 | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | `uint16` | - |
| Battery voltage (mV) | 10 | 1 | `uint8` | `/20` |
| NH3 (?) | 11 | 1 | `uint8` | - |

Frame size = 12
Max frames per packet = 20

## Fixed Finedust

### Sensors
- PMS5003 [Finedust]
- BME280 [Temperature, Humidity, Pressure]

### Default properties
| Property | Value |Fixed |
|-------------|----------------------|-------|
| Name | `MAFD0000` | No |
| Mac address | `FF:48:33:22:11:CD` | No |
| Profile ID | `0x04` | Yes |

### Broadcast
| Data | Element | Size | Type | Data Type | Factor |
|-------------------------------------|---------|------|---------|-----------|--------|
| Manufacturer specific size(0x1D) | 0 | 1 | Company | `uint8` | - |
| AD type manufacturer specific(0xFF) | 1 | 1 | Company | `uint8` | - |
| Company ID(tbd, 0xFF) | 2-3 | 2 | Company | `uint16` | - |
| Temperature (°C) | 4-5 | 2 | MyAir | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | MyAir | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | MyAir | `uint16` | - |
| PM 1.0 | 10-11 | 2 | MyAir | `uint16` | - |
| PM 2.5 | 12-13 | 2 | MyAir | `uint16` | - |
| PM 10 | 14-15 | 2 | MyAir | `uint16` | - |
| PC 0.3 | 16-17 | 2 | MyAir | `uint16` | - |
| PC 0.5 | 18-19 | 2 | MyAir | `uint16` | - |
| PC 1.0 | 20-21 | 2 | MyAir | `uint16` | - |
| PC 2.5 | 22-23 | 2 | MyAir | `uint16` | - |
| PC 5.0 | 24-25 | 2 | MyAir | `uint16` | - |
| PC 10 | 26-27 | 2 | MyAir | `uint16` | - |

### Memory data
| Data | Element | Size | Data Type | Factor |
|-------------------------------------|---------|------|-----------|--------|
| Timestamp (epoch) | 0-3 | 4 | `uint32` | |
| Temperature (°C) | 4-5 | 2 | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | `uint16` | - |
| PM 1.0 | 10-11 | 2 | `uint16` | - |
| PM 2.5 | 12-13 | 2 | `uint16` | - |
| PM 10 | 14-15 | 2 | `uint16` | - |
| PC 0.3 | 16-17 | 2 | `uint16` | - |
| PC 0.5 | 18-19 | 2 | `uint16` | - |
| PC 1.0 | 20-21 | 2 | `uint16` | - |
| PC 2.5 | 22-23 | 2 | `uint16` | - |
| PC 5.0 | 24-25 | 2 | `uint16` | - |
| PC 10 | 26-27 | 2 | `uint16` | - |

Frame size = 28
Max frames per packet = 8

## Fixed CO2

### Sensors
- TDE5514 [CO2]
- BME280 [Temperature, Humidity, Pressure]

### Default properties
| Property | Value |Fixed |
|-------------|----------------------|-------|
| Name | `MAC02000` | No |
| Mac address | `FF:49:33:22:11:CD` | No |
| Profile ID | `0x05` | Yes |

### Broadcast
| Data | Element | Size | Type | Data Type | Factor |
|-------------------------------------|---------|------|---------|-----------|--------|
| Manufacturer specific size(0x1D) | 0 | 1 | Company | `uint8` | - |
| AD type manufacturer specific(0xFF) | 1 | 1 | Company | `uint8` | - |
| Company ID(tbd, 0xFF) | 2-3 | 2 | Company | `uint16` | - |
| Temperature (°C) | 4-5 | 2 | MyAir | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | MyAir | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | MyAir | `uint16` | - |
| CO2 (ppm) | 10-11 | 2 | MyAir | `int16` | - |

### Memory data
| Data | Element | Size | Data Type | Factor |
|-------------------------------------|---------|------|-----------|--------|
| Timestamp (epoch) | 0-3 | 4 | `uint32` | |
| Temperature (°C) | 4-5 | 2 | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | `uint16` | - |
| CO2 (ppm) | 10-11 | 2 | `int16` | - |

Frame size = 12
Max frames per packet = 20

## Fixed NH3

### Sensors
- ? [NH3]
- BME280 [Temperature, Humidity, Pressure]

### Default properties
| Property | Value |Fixed |
|-------------|----------------------|-------|
| Name | `MANH3000` | No |
| Mac address | `FF:4A:33:22:11:CD` | No |
| Profile ID | `0x06` | Yes |

### Broadcast

| Data | Element | Size | Type | Data Type | Factor |
|-------------------------------------|---------|------|---------|-----------|--------|
| Manufacturer specific size(0x1D) | 0 | 1 | Company | `uint8` | - |
| AD type manufacturer specific(0xFF) | 1 | 1 | Company | `uint8` | - |
| Company ID(tbd, 0xFF) | 2-3 | 2 | Company | `uint16` | - |
| Temperature (°C) | 4-5 | 2 | MyAir | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | MyAir | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | MyAir | `uint16` | - |
| NH3 (?) | 10 | 1 | MyAir | `uint8` | - |

### Memory data
| Data | Element | Size | Data Type | Factor |
|-------------------------------------|---------|------|-----------|--------|
| Timestamp (epoch) | 0-3 | 4 | `uint32` | |
| Temperature (°C) | 4-5 | 2 | `int16` | `x100` |
| Humidity (%RH) | 6-7 | 2 | `uint16` | `x100` |
| Pressure (hPa) | 8-9 | 2 | `uint16` | - |
| NH3 (?) | 10 | 1 | `uint8` | - |

Frame size = 11
Max frames per packet = 22

# MyAir Tasks [P2P]

_Last updated: release v2.18.2_
# MyAir Task Service
MyAir task is a custom protocol made for MyAir. This allows client devices to give tasks or instructions to MyAir over BLE in a peer-to-peer connection. A task can be anything. Examples of tasks are `Sync Time` (will synchronize the time with the RTC), `System Reboot` (will reboot the system), or `sync data` (will synchronize the sensor data). This document will mainly focus on documenting the available tasks and describing their interface. If you want a more in-depth knowledge of the task interface itself and how to use it or add new tasks, you should visit the [Task Interface](https://github.com/VTECadmin/myAir-embedded-ble/wiki/Task-interface) wiki page.

## Opcodes

| Name | Opcode | Normal mode | Dummy mode | Description |
|------------------|--------|-------------|------------|------------------------------------------------------|
| `NULL-Task` | `0x00` | - | - | Reserved. |
| | | | | |
| `Sync Time` | `0x10` | Yes | Not yet | Sync/set time with MyAir. |
| `Fetch Time` | `0x11` | Yes | No | Fetch time from MyAir. |
| `Sync Data` | `0x12` | Yes | Yes | Get all sensor data from memory. |
| `Clear Memory` | `0x13` | Yes | No | Remove all sensor data from memory (set all to `0`). |
| `Get Frame` | `0x14` | Yes | Yes | Get one frame (1 minute) from the memory. |
| | | | | |
| `Device Name` | `0x20` | Yes | No | Set device name in MyAir (max. 8 chars). |
| `Fetch Name` | `0x21` | Yes | No | Fetch device name from MyAir. |
| `Clear Name` | `0x22` | Yes | No | Set device name to Default (set in profile). |
| `Set Mac` | `0x23` | No | No | Set Mac address in MyAir (update after reboot). |
| `Fetch Mac` | `0x24` | No | No | Fetch Mac Address from MyAir. |
| `Clear Mac` | `0x25` | No | No | Set Mac address to default (set in profile). |
| `Set GUID` | `0x26` | No | No | Set GUID in MyAir. |
| `Fetch GUID` | `0x27` | No | No | Fetch GUID from MyAir. |
| `Clear GUID` | `0x28` | No | No | Set GUID to default. |
| `Set Finfo` | `0x29` | No | No | Set factory information (128 chars). |
| `Fetch Finfo` | `0x2A` | No | No | Fetch factory information from MyAir. |
| `Clear Finfo` | `0x2B` | No | No | Set Factory Information to default. |
| `Clear Metadata` | `0x2C` | No | No | Set all metadata to default. |
| | | | | |
| `Sys Reboot` | `0xC0` | Yes | No | Reboots the system. |
| `Sys Freeze` | `0xC1` | Yes | No | Freeze system (simulate system crash). |
| `TWI Ping` | `0xc2` | Yes | No | Checks if a TWI-device responds to that address. |
| `TWI scan` | `0xC3` | Yes | No | Gives a list of all connected TWI-device addresses. |

## Modes
| Mode | Code | Behaviour |
|----------|--------|---------------------------------------------------------------------|
| `NULL` | `0x00` | Reserved. |
| `Normal` | `0x01` | This mode will execute the task. |
| `Dummy` | `0x02` | This mode will fake/simulate the response (does not execute task). |
| `Skip` | `0x03` | This mode will only check if the task exist(does not execute task). |

## Error codes

| Error | Code | Description |
|---------------------|--------|-------------------------------------------------|
| `Success` | `0x00` | No errors. 👍 |
| `Unknown Error` | `0xFF` | Unknown error. ❓ |
| `Invalid Opcode` | `0x01` | That opcode does not exist. |
| `Invalid Mode` | `0x02` | That mode does not exist. |
| `Invalid Parameter` | `0x03` | The parameter for the task is wrong or missing. |
| `System Error` | `0x04` | Something went wrong in the system. |

***

# Available tasks

## Sync time (`0x10`)

This task will synchronize time and enable the backup-battery for the RTC.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |
| Epoch timestamp | [Timestamp] | 2-5 | `uint32` |

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Epoch timestamp | [Timestamp] | 0-3 | `uint32` | Little endian.

### Behavior (Normal)

This task will enable the RTC (PCF8523) backup-battery to make sure that during power-loss the time is still stored. It will also set the time in the RTC.
After the time is set, it will then fetch the time and echo it to the client. If the timestamp is correct and RTC did response during all three operations, the task will return `Success` error code.

### Behavior (Dummy)
It will only verify the timestamp and echo the given timestamp. And then exit with a `Success` error code.

## Fetch time (`0x11`)

This task will fetch and return the time from the RTC.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Epoch timestamp | [Timestamp] | 0-3 | `uint32` | Little endian.

### Behavior (Normal)

This task will fetch and return the time from the RTC in epoch format. If the RTC did respond it will return a `Success` error code.

### Behavior (Dummy)
None

## Sync data (`0x12`)

This task will send the entire memory to the client.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x12` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|-------------|:-----
| Memory frame | [Frame] | 0 - x | `structure` | Profile dependent
### Behavior (Normal)
Returns all data from the memory. To maximize throughput and reduce overhead, the memory will put as many frames in a single packet as can fit. The amount of frames that can fit in a single, packet, as well as the frame size is defined in [MyAir profiles](https://github.com/VTECadmin/myAir-embedded-ble/wiki/MyAir-profiles) wiki page. Also the amount of data frames in a single packet can vary. Usually it is the maximum defined frames per packet, but in example there are only two frames left on the memory, and the packet can hold 10 frames, the sensor will only send those two frames.

### Behavior (Dummy)
None

## Sync data (`0x12`)

This task will send the entire memory to the client.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x12` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response
Only error code.

### Behavior (Normal)
This task will clear the full sensor-data section of the memory (it will not overwrite the metadata or another part of the memory). All data will be set to `0`. If the memory chip respond to all operations, the task will return a `Success` error code.

### Behavior (Dummy)
None

## Get Frame (`0x14`)

This task will send one frame (1 minute data) from the memory.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x14` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |
| Epoch timestamp | [FrameNo] | 2-3 | `uint16` | Max. 1439

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|-------------|:-----
| Memory frame | [Frame] | 0 - x | `structure` | Profile dependent
### Behavior (Normal)

This task will get a single memory frame from the memory and send it. If the task could read from the memory, it will return `Success` error code.

### Behavior (Dummy)
It will verify the parameters and return a frame (length remains the same). The timestamp is faked, the data will be hex `0405060708090A...`. The timestamp is calculated has the base epoch timestamp `1589813916` for frame (minute) `0` and it add 60 seconds for every frame after that. See snippet below.

timestamp = 1589813916 + (frameNo * 60);

Then the function will exit with a `Success` error code.

## Device name (`0x20`)

This task will verify and store the device name.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |
| Device name (ascii) | [ASCII] | 2-x | `char[]` | 1 to 8 characters. ASCII 0x21 to 0x7E.

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Device name (ascii) | [ASCII] | 0-x | `char[]` | 1 to 8 characters. ASCII 0x21 to 0x7E.

### Behavior (Normal)

This task will verify the device name (length and characters) and, if valid, store the device name. Then it will fetch the device name and return it. You can already fetch the device name with the `Fetch name` task, but the name will only be updated in system (and broadcast) after a reboot or power-cycle.

### Behavior (Dummy)
None

## Fetch name (`0x21`)

This task will synchronize time and enable the backup-battery for the RTC.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Device name (ascii) | [ASCII] | 0-x | `char[]` | 1 to 8 characters. ASCII 0x21 to 0x7E.

### Behavior (Normal)

This task will fetch and verify the device name. If the name contains invalid characters, it will return the default name (defined in profile) instead (because this name will also be used by the system in case of invalid name) and give an error code. If the memory did respond and the name is valid, it will return `Success` error code.

### Behavior (Dummy)
None

## Clear name (`0x22`)

This task will overwrite the device name with the (profile defined) device name.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Device name (ascii) | [ASCII] | 0-x | `char[]` | 1 to 8 characters. ASCII 0x21 to 0x7E.

### Behavior (Normal)

This task will set the device-name to the default name (defined in profile). After this, it will fetch the name from the device and return it. If the memory did respond and the name is valid, it will return `Success` error code. If you execute `fetch name` task, you will get this name returned but it will update in the system (and broadcast) after a system reboot or power-cycle.

### Behavior (Dummy)
None

## Sys reboot (`0xC0`)

This task will reboot the system.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

None, you won't receive any disconnect or error code (you will receive a timeout probably).

### Behavior (Normal)

This task will reboot the system.

### Behavior (Dummy)
None

## Sys freeze (`0xC1`)

This task will freeze the system.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

None, you won't receive any disconnect or error code (you will receive a timeout probably).

### Behavior (Normal)

This task will cause the system to freeze. Internally, it will disable the IRQ (so no interrupts can be generated) and enter an infinite loop (which blocks the system from running). This task will simulate a system crash. After a few seconds, the WDT should kick in and reboot the system.

### Behavior (Dummy)
None

## TWI ping(`0xC2`)

This task will ping an address on the TWI network.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |
| Address | [TWI Addr] | 2 | `uint8` | Between 0 and 127.

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Address | [Addr] | 0 | `uint8` | Between 0 and 127.
| Response | [Response] | 1 | `bool` | 0 for no response, 1 for did respond.

### Behavior (Normal)

This task will verify the address ping the given address on the TWI/I2C network. It will return the address and a boolean with the response of the address. It will return a `0` or `false` if the address didn't respond, or a `1` or `true` if it did.

### Behavior (Dummy)
None

## TWI scan(`0xC3`)

This task scan for valid device addresses on the TWI network and return a list of all the valid addresses.

### Request

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Opcode | `0x10` | 0 | `uint8` |
| Mode | [Mode] | 1 | `uint8` |

### Response

| Item | Value | Element | Data type | Note
|---------------------|-------------|---------|------------|:-----
| Address | [Addr list] | 0-x | `uint8` |

_Note: This frame is at least two bytes long to differentiate with error codes. If No addresses are found it will not send this frame._

### Behavior (Normal)

This task will scan the TWI/I2C network and return a list of all valid addresses. If only one valid address is found, it will send that address twice to differentiate itself from an error code. If no addresses are found, it will just send the `success` error code.

### Behavior (Dummy)
None