# EIoTC Bidirectional Overview

With 1.6 release EnOcean IoT Connector added bidirectional support for EnOcean devices. Currently only two devices are supported:

1. [Micropelt iTRV MVA004](https://www.micropelt.com/en/products/enocean/mva004) **Product ID:** 004900000005 - **Default Unlock Code:** FFFFFFFE
1. [Eltako FSVA-230V-10A](https://www.eltako.com/en/product/professional-standard-en/three-phase-energy-meters-and-one-phase-energy-meters/fsva-230v-10a/) **Product ID:** 000D30100003

## Adding Devices to IoTC

When adding devices for bidirectional communication using the API **deviceType** parameter should be "bidirectional" and **productId** field should exist. If the device is controlled using Remote Commisioning an additional field **unlockCode** should be given. 

### Adding Micropelt iTRV

POST request to /devices using the API with payload below

```
{
  "eurid": "051ad57d",
  "destinationEurid": "ffffffff",
  "deviceType": "bidirectional",
  "friendlyid": "trv",
  "location": "Level 2 / Room 221",
  "eep": "A5-20-01",
  "productId": "004900000005",
  "unlockCode": "FFFFFFFE"
}
```

After device is added TRV is paired with IoTC automatically on received message from TRV.

### Adding Eltako FSVA

POST request to /devices usign the API with payload below

```
{
  "eurid": "ff846680",
  "destinationEurid": "ffffffff",
  "deviceType": "bidirectional",
  "friendlyid": "fsva",
  "location": "Level 2 / Room 221",
  "eep": "A5-12-01",
  "productId": "000D30100003",
}
```

To pair this device to IoTC following steps must be followed. This guide will assume device is in factory reset conditions:

- Plug the device in pressing both buttons on the device to enable reporting.
- Within 5 second of plugging in the device, device should be switched learn-in mode (press left button for 3 seconds until device starts blinking red led then press right button two times)
- IoTC will send RPS to teach itself into the device.
- After 1 seconds EIoTC will try to toggle the device two times to make sure that it's configured for controlling the device. You might hear clicks from the device. 
- Device is ready for controlling


## Controlling the devices 

### MQTT Interface

**Topics**

You can control the bidirectional devices using MQTT. Below are 3 topics used. 

Topic for queuing new commands
```
device/{device_id}/rpc/command
```
Topic for deleting waiting commands
```
device/{device_id}/rpc/cancel
```
Topic for results of requests
```
device/{device_id}/rpc/result
```

**Making requests**

Publish the request to `device/{device_id}/rpc/command` topic as json with the schema below. Examples for each device will be provided later.
```
{
  "request_id": 1,
  "eep": "a5-20-01",
  "payload": { 
    "summerMode": 0,
    "temperature": 0,
    "temperatureSetpoint": 0,
    ...
    }
}
```

| key | type and meaning |
| --- | --- |
| request_id | integer, unique identifier generated by user |
| eep | string, EnOcean Equipment Profile. This can be different from device's reporting EEP. |
| payload | object, command payload using keys from JSON representation of EEP see [here](http://tools.enocean-alliance.org/EEPViewer/profiles/A5/20/01/A5-20-01.json) |

**Results**

After request is done watch `device/{device_id}/rpc/result` for results of the request
```
{
    "request_id": 1,
    "success": true,
    "device_id": "051ad57d",
    "message": "Command successfuly queued"
}
```

|key|type and meaning|
|---|---|
|request_id|integer, unique identifier of RPC request|
|success|boolean, status of request|
|device_id|string, ID of device|
|message|string, explanation of request's current state|

If everything works fine results below will follow:
```
{
    "request_id": 1,
    "success": true,
    "device_id": "051ad57d",
    "message": "RPC Command successfully transcoded [buffer=55:00:0A:07:01:EB:A5:00:00:00:08:DE:AD:BE:EF:00:03:FF:FF:FF:FF:FF:00:58]"
}
```
```
{
    "request_id": 1,
    "success": true,
    "device_id": "051ad57d",
    "message": "RPC request sent to device"
}
```

Possible error messages are as below:

Device not added to EIoTC
```
{
  "success": false,
  "request_id": -1,
  "device_id": "11111111",
  "message": "Device does not exist"
}
```

Device exists in EIoTC but not configured to be controlled
```
{
  "success": false,
  "request_id": -1,
  "device_id": "11111111",
  "message": "Device is not paired"
}
```

Invalid json schema
```
{
  "success": false,
  "request_id": -1,
  "device_id": "11111111",
  "message": "JSON decoding error. Given payload is not a valid JSON."
}
```

One of the required keys of EEP is missing
```
{
  "success": false,
  "request_id": -1,
  "device_id": "11111111",
  "message": "Payload doesn't comply with given EEP(A5-20-01). [valve] is missing"
}
```

Device is not bidirectional
```
{
  "success": false,
  "request_id": -1,
  "device_id": "11111111",
  "message": "Device is not supported for RPC Command"
}
```

**Canceling existing request**

Publish cancelation request to `device/{device_id}/rpc/cancel` topic as json with the schema below.
```
{
  "request_id": 1,
  "device_id": "051ad57d"
}
```
After cancelation request is done watch `device/{device_id}/rpc/result` for results of the request
```
{
    "request_id: 1,    
    "success": true,
    "device_id": "051ad57d",
    "message": "RPC command cancelled"
}
```

### Controlling Micropelt iTRV

Since Micropelt is an energy harvesting device it's not always on. It sends a 4BS telegram every 1 hour. EIoTC sends the RPC commands to device on receiving said telegrams. Request can be made at any point, IoTC will wait for device to wake up. EIoTC can control iTRV using valve position functionality of device. To set the device to valve position "valve" parameter in json can be changed. Range is between 0 and 100. EEP is always "a5-20-01"

```
{
    "request_id": 1,
    "eep": "a5-20-01",
    "payload": {
        "valve": 43,
        "temperature": 0,
        "runInitSequence":0,
        "runLiftSet":0,
        "valveOpen": 0,
        "valveClosed": 0,
        "summerMode": 0,
        "setPointSelection": 0,
        "setPointInverse": 1,
        "selectFunction": 0,
        "learnBit": 0
    }
}
```

[EEP Documentation](http://tools.enocean-alliance.org/EEPViewer/profiles/A5/20/01/A5-20-01.pdf)

### Controlling Eltako FSVA-230V

Due to device specifications EIoTC controls FSVA using RPS type telegrams. Which is to say EIoTC simulates behaviour of EnOcean PTM. To turn on the device json below can be published to command topic.

```
{
    "request_id": 1,
    "eep": "f6-02-01",
    "payload": {
        "R1": 0,
        "EB": 1,
        "R2": 0,
        "SA": 0
    }
}
```

To turn off the device use command below.
```
{
    "request_id": 1,
    "eep": "f6-02-01",
    "payload": {
        "R1": 1,
        "EB": 1,
        "R2": 0,
        "SA": 0
    }
}
```
