abs96serial/Readme.md

> [!WARNING]
> The documentation and code in this repository are provided 'as is' with no warranty or guarantee as to their completeness or accuracy. The information may be incomplete, out of date or otherwise incorrect. As the integrator, you are responsible for correctly interpreting any data received from the device.

# Byonoy Absorbance 96 Serial Interface

> [!IMPORTANT]
> This protocol is used __only__ by the manual variant of Absorbance 96; it is not used by the Automate variant or any other Byonoy device. If you need to control any other Byonoy device via code, please [contact support](https://byonoy.com/support/) to request access to the SDK.

Communication takes place in human-readable form via the serial interface.

| Parameter | Value |
| --------- | ------ |
| Baud rate | 115200 |
| Data bits | 8 |
| Parity | None |
| Stop Bits | 1 |

The `!RP` and `!RPF` commands transmit a CRC checksum in their data payload. Details on request. The measurement results ("Optical density data") are transmitted in 12 rows. A1 to H1, A2 to H2 etc. Wavelengths are indexed by their physical position in the device:

| Index | Meaning                                                                 |
| ----- | ----------------------------------------------------------------------- |
| -1    | Do not measure (e.g. `!RP(0,-1)` measures Slot 0 and uses no reference) |
| 0     | First slot (e.g. 492nm)                                                 |
| 1     | Second slot (e.g. 450nm)                                                |
| 2     | Third slot (e.g. 405nm)                                                 |
| 3     | Forth slot (e.g. 620nm)                                                 |

## Serial Commands

Send one command followed by a line break. The device will echo the received command, then a line break, then the data payload, then a postamble. The postamble is usually `#<Command>()` except the `!RP*` commands, which all send `#RP()` as postamble.

| **Command**       | **Result**                                                                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `!GETFILT()`      | Returns installed filters                                                                                                                                  |
| `!RPF(x,y)`       | <p>Read Plate </p><p>x: Measurement wavelength index </p><p>y: Reference wavelength index </p><p>Returns: OD at wavelength x minus OD at wavelength y </p> |
| `!RPP(x,y)`       | Read Plate; same as RPF, but formatted for human readability                                                                                               |
| `!PLATE()`        | Returns: 1 if a microplate is in the device or state is not known. 0 otherwise                                                                             |
| `!CALIBRATE(x,y)` | Perform initialization and zero for wavelength indices x and y                                                                                             |
| `!ERROR()`        | Returns current error code (0 = No Error)                                                                                                                  |
| `!SN()`           | Returns serial number                                                                                                                                      |
| `!VERSION()`      | Returns firmware version                                                                                                                                   |

## Example Communications

> [!TIP]
> The [official app](https://byonoy.com/download-hub/absorbance-96/) is available free of charge. It can be used as an easy-to-access reference tool, as it logs all serial communications in the app's log file.

The arrow denotes direction of data flow: `->` is host to device, `<-` is device to host.

### List available wavelengths

- `->` `!GETFILT()`
- `<-` `!GETFILT()`
- `<-` `0=405,1=450,2=492,3=620`
- `<-` `#GETFILT()`

### Read current temperature

- `->` `!TEMP()`
- `<-` `!TEMP()`
- `<-` `Temperature:  23.43 C`
- `<-` `#TEMP()`

### Perform measurement

- `->` `!RPF(0,-1)`
- `<-` `!RPF(0,-1)`
- `<-` `0.115 0.125 0.147 0.120 0.127 0.175 0.146 0.133`
- `<-` `0.084 0.104 0.108 0.115 0.096 0.194 0.162 0.198`
- `<-` `0.062 0.072 0.080 0.097 0.070 0.119 0.132 0.106`
- `<-` `0.130 0.067 0.064 0.113 0.072 0.105 0.128 0.155`
- `<-` `0.100 0.083 0.066 0.080 0.057 0.075 0.065 0.106`
- `<-` `0.069 0.050 0.064 0.074 0.090 0.084 0.100 0.097`
- `<-` `0.051 0.059 0.056 0.065 0.058 0.064 0.058 0.101`
- `<-` `0.071 0.075 0.077 0.070 0.084 0.113 0.083 0.113`
- `<-` `0.100 0.079 0.072 0.069 0.083 0.100 0.133 0.131`
- `<-` `0.074 0.079 0.074 0.093 0.122 0.132 0.117 0.170`
- `<-` `0.138 0.101 0.094 0.110 0.156 0.161 0.168 0.172`
- `<-` `0.187 0.153 0.142 0.128 0.111 0.144 0.118 0.107`
- `<-` `1236585622 CRC`
- `<-` `Temperature:  27.06 C`
- `<-` `Measurement time: 2.1 seconds`
- `<-` `Filters 0/-1 (405nm/0)`
- `<-` `#RP()`

Check for plate in device

- `->` `!PLATE()`
- `<-` `1`
- `<-` `#PLATE()`

## Error Codes

- Severity 1: resets to error code 0 after the error was polled with !ERROR().
- Severity 2: device must be reconnected for reset.
- Severity 3: device is damaged.

| **Error Code** | **Severity** | **Description**                                                                                                        |
| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| 0              | N/A          | OK                                                                                                                     |
| 1              | 1            | Optical problem. Device dirty or damaged.                                                                              |
| 2              | 1            | Ambient light exceeded tolerated level. (not applicable for automated variant)                                         |
| 3              | 2            | USB power insufficient. Remove hub, replace cable or change USB port                                                   |
| 4              | 3            | Hardware error                                                                                                         |
| 5              | 1            | <p>Temperature warning / error </p><p>- 0 to 50°C warning </p><p>- < 0 or > 50°C error → device stops functioning </p> |

### Typical workflow (measure wavelength at second slot and no reference wavelength)

**Step 1:** no plate inserted. Calibrate zero values for required wavelengths:

`!ERROR()` → if > 0 : retry

`!CALIBRATE(1,-1)`

`!ERROR()` → if > 0 : zero failed. retry step 1

**Step 2:** Insert microplate, then attempt measurement:

`!RPF(1,-1)`

`!ERROR()` → if = 0 results valid

It is recommended to execute `CALIBRATE` before every endpoint measurement and before the first measurement of a kinetic series, respectively. Step 2 should be started within 15 minutes of completing step 1 for optimal performance.