# WInFiDEL - Serial API

WInFiDEL currently supports the following APIs that can be used to interact and/or integrate with other systems:

- Serial API (this document)
- [WebAPI](https://docs.sasakaranovic.com/winfidel/web_api/index.md)

Currently WInFiDEL has a very simple interface that just prints out every diameter measurement it takes.

When enabled, it will print out a diameter measurement every 200ms (or 5 measurements per second).

## Enable serial diameter printout

WInFiDEL will not print diameter data over serial until the host machine indicates that it is ready to receive diameter data.\
Host machine can request/enable serial diameter printout by sending a single start character which is either `s` or `S`.

> **NOTE: Onboard RGB LED meaning**
>
> Onboard RGB LED will blink once per every 2 diameter samples taken.\
> Teal color indicates serial printout is enabled.\
> Green color indicates serial printout is disabled.

> **WARNING: Serial buffer**
>
> WInFiDEL relies on internal Serial buffer for writing diameter data.\
> If host machine is not reading serial data or not reading it fast enough, this internal buffer could fill up and cause time-outs and slower sampling times.\
> It is recommended to disable serial diameter printout if it's not actively used.

## Disable serial diameter printout

Host machine can disable serial diameter printout by sending a single end character which is either a `e` or `E`.

## Example serial printout

The serial printout will look something like this

```text
*wm:AutoConnect
*wm:Connecting to SAVED AP: Your-SSID
*wm:connectTimeout not set, ESP waitForConnectResult...
*wm:AutoConnect: SUCCESS
*wm:STA IP Address: 192.168.180.164
Connected.
WiFi IP: 192.168.180.164
mDNS http://winfidel.local
Calibration loaded from EEPROM
Starting WebServer...done.
WiFi IP: 192.168.180.164
Arduino OTA is on
Ready to go.
Scanning...
I2C device found at address 0x4D  !
done

Entering main loop
```

At this point WInFiDEL is expecting the host machine to send a start character `s` which indicates that the host is ready to start receiving diameter data.

After receiving start character, the WInFiDEL will start to send diameter every 0.2s

```text
>1.71mm
>1.71mm
>1.71mm
>1.70mm
>1.70mm
>1.70mm
>1.71mm
>1.71mm
```

The host machine can at any time send end character `e` which indicates that the host no longer wishes to receive diameter data. This will stop serial diameter printout.

> **NOTE: Serial port configuration**
>
> Once you connect the WInFiDEL board to a PC (or a USB host) it will appear as a USB serial port (ie. `COM1` or `/dev/ttyACM0`).\
> It communicates using 115200 baud rate (1 stop bit, no parity, no handshaking)

> **WARNING: Time synchronization**
>
> WInFiDEL collects and prints out measurements in real-time. However it does not print or keep track of time.\
> If you require time-stamps, you can (on the receiving end) synchronize WInFiDEL's real-time measurements to your system clock.

## Collecting data over serial

There are many ways to collect WInFiDEL's serial printout.

In the below example we will use Python and RegEx to collect measurements.

```python
import re
import time
import serial

ser = serial.Serial()
ser.port = 'COM5'          # e.g. /dev/ttyACM0 on Linux
ser.baudrate = 115200
ser.timeout = 1
ser.dtr = False            # set before open(): toggling DTR/RTS resets the board
ser.rts = False            # or puts it in bootloader mode
ser.open()

time.sleep(2)              # let boot messages finish if the board did reset
ser.reset_input_buffer()
ser.write(b's')            # start diameter printout

pattern = re.compile(r'^>(\d+\.\d{1,2})mm$')

try:
    while True:
        line = ser.readline().decode('utf-8', errors='ignore').strip()
        m = pattern.match(line)
        if m:
            print(float(m.group(1)))
except KeyboardInterrupt:
    pass
finally:
    ser.write(b'e')        # stop printout so the device buffer doesn't fill
    ser.close()
```

> **NOTE**
>
> Above example assumes you have already installed [pySerial](https://pyserial.readthedocs.io/en/latest/pyserial.html#installation)

> **WARNING**
>
> Note that WInFiDEL uses flow-control for reset and/or to put the board into bootloader mode.

## Example RegEx

WInFiDEL will always print diameter as `>1.71mm`

There is always `>` at the beginning of the line.\
Followed with the diameter (ie. 1.71).\
And finally there is `mm` indicating units followed with `\r\n`.

One simple RegEx patterns that you can use to find diameter measurements is:

```text
>([0-9]\.[0-9]{0,2})mm
```