# SplitflapBus protocol
## Terminology
* *main controller interface*: RS485 interface, connected to the mangment pc. Serves as bus master.
* *node*: Participant on bus. Can be a controller interface or an flap controller.
* *flap controller*: Microcontroller located in each flap module that processes requests and drives motor.

## Protocol implementation
The SF-Bus is an RS485 based protocol. It has a singular master node and up to 32 client *nodes* per interface.  It can address up to 65536 *devices*.

The communication is always initiated by the *main controller interface*, serving as the bus *master*.
The start of a new communication is signaled by sending the start byte `0x2B` to the bus, followed by the protocol version (8-bit) and frame length (8-Bit). Each connected *node* now captures the entire packet, even if the adress does not match its own. This reduces the risk of the *node* falsely identifying payload data as a start byte if it contains the value `0x2B`.

After the transmission of the payload length, the receiver *node* counts the remaining packages and terminates the transmission at 0 bytes remaining. The data is written to a buffer for further processing.

In protocol version 1.0, the receiving *node* expects the last byte to be `0x24`. If this is not the case, the transmission is marked as invalid and will not be processed further. The receiving *node* will not send any response.

In protocol version 2.0, the checksum of the payload is verified. If it does not match the payload, the transmission is marked as invalid and will not be processed further. The receiving *node* will not send any response.
No stop-byte is expected. Version 2.0 also requires a timeout-check in the receiving function. This allows the bus to support hot-plugging, to cancel incomplete or invalid packages and reliably detect the start of a new transmission.

The communication is typically unidirectional. Lost transmissions are not detectable. The *flap controller* NEVER initiates a communication to the *main controller interface*. *node* to *master* communication only occures in response to specific commands. This is specified in the command / payload documentation.

## Packet format (2.0)
```
+---------------------------------+----------------------------------------+
| Header                          | Frame                                  |
+------------+-----------+--------+----------+-----------------+-----------+
| Start-Byte | Protocol- | Frame- | Receiver | Payload         | Checksum  |
|            | Version   | Length | Address  |                 |           |
| 0x2B       | 0x01      | 1 byte | 2 bytes  | framelength - 4 | 2 bytes   |
+------------+-----------+--------+----------+-----------------+-----------+
 The frame length includes the 16-bit address and 16 bit checksum.
 Therefor, the payload is framelegth - 4.

 Checksum is based on MODBUS CRC algorithm. Check implementation in sfbus.c
 Checksum is only created for the payload, not the entire frame or packet.
```

More infromation regarding the crc algorithm: https://ctlsys.com/support/how_to_compute_the_modbus_rtu_message_crc/

## Payload format (Protocol Version 1.0 + 2.0)
The first byte of the payload is the command. This tells the controller
what to do or what data to expect next.

```
+----------+----------------+
| Command  | Payload        |
| Byte     |                |
| 1 Byte   | framelegth - 4 |
+----------+----------------+
```


### Ping
Check if a module is present under this device id
- Payload: `0xFE`
- Expected response: `0xFF`

### Reset
Resets the device controller. Should be done after address or calibration change.

Can also be done to clear error flags
- Paylad `0x30`
- Expects no response.

### Motor power on
- Paylad `0x21`
- Expects no response.

### Motor power off
- Paylad `0x20`
- Expects no response.

### Display flap
- Paylad `0x10 <1 byte: flap id>`
- Expects no response.

### Display flap with full rotation
- Paylad `0x11 <1 byte: flap id>`
- Expects no response.

### Read EEPROM
Read address and calibration configuration from internal non-volatile memory.
- Payload `0xF0`
- Response is `0xAA` followed by content of EEPROM (5 bytes). See mapping below.

### Write EEPROM
Write address and calibration configuration to internal non-volatile memory.
- Payload `0xF1 <5 bytes of eeprom content>`
- Response is `0xAA` followed by new content of EEPROM (5 bytes). See mapping below.

### Get controller status
- Payload `0xF8`
- Response is 7 bytes long.

```
+--------+------------+------------+
| Byte 0 | Byte 1 - 2 | Byte 3 - 6 |
| 8-Bit  | 16-Bit     | 32-Bit     |
| Status | Voltage    | Rotations  |
+--------+------------+------------+
  |         |            |
  |         |            +-> uint32 counter of total rotations
  |         |
  |         +-> uint16 raw ADC readings.
  |             double __voltage = ((double)_voltage / 1024) * 55;
  |
  +->   Bit 0:  delta too big. Sensed position not equal to expected position
        Bit 1:  no home found. Cannot sense home magnet.
        Bit 2:  fuse blown
        Bit 4:  device powered down. Can be changed by sending: 0x21
        Bit 5:  failsafe active. Device failed cirtically and stopped operation.
                can be recovered with reset: 0x30
        Bit 6:  device busy. Device is currently moving to the next flap position

```

## EEPROM format
```
+------------+------------+--------+
| Byte 0 - 1 | Byte 2 - 5 | Byte 6 |
| 16-Bit     | 32-Bit     | 8-Bit  |
| Address    | Rotations  | Okay   |
+------------+------------+--------+
  |             |           |
  |             |           +-> do not change
  |             |
  |             +-> uint32 counter of total rotations
  |
  +-> uint16 device address
```

## Address management
* Address `0x0000` is reserved for new devices. These devices needs a new address before it can be used. Use the `Write EEPROM` method to change it.
* Address `0xFFFF` is reserved for the bus *master* and must never be used by another node. Each *node* to *master* response package must be sent to this address.
* All remaining addresses can be freely assigned.