Firmware

The shared sketch is 2P1V_Adafruit.ino in 2P1V_Adafruit. Use Arduino IDE 2.x and the board SparkFun ESP32 Thing Plus. This page applies to RheoBoardOTS - DIY, RheoBoard_v1 - PCB, and RheoBoardPipette - Portable. The pin map is in Firmware controls. RheoData is on Software.

RheoBoardOTS - DIY builders reach this page from Assembly Step 04. PCB and portable builds use the install steps below and do not continue into the DIY adapter steps.

Install

1. Download the repository.

git clone https://github.com/The-Hybrid-Atelier/RheoBoard.git

2. Open RheoBoard/code/firmware/2P1V_Adafruit/. It holds 2P1V_Adafruit.ino, PneumaticSystem.h, PneumaticSystem.cpp, RheoSystem.h, and RheoSystem.cpp. In Arduino IDE, open 2P1V_Adafruit.ino. Leave the folder name as 2P1V_Adafruit. The folder name has to match 2P1V_Adafruit.ino.
3. Open Settings (macOS) or Preferences (Windows and Linux). Paste this URL into Additional boards manager URLs.

https://espressif.github.io/arduino-esp32/package_esp32_index.json

4. Open Boards Manager. Install the esp32 package by Espressif Systems.
5. Install these libraries from Library Manager.

Library	Where
SparkFun Qwiic Button	Library Manager
SparkFun MicroPressure	Library Manager
Adafruit seesaw Library	Library Manager
OSC by Adrian Freed	Library Manager

6. Find the sketchbook location in that same Settings or Preferences window. If you have not moved the sketchbook, the usual macOS location is ~/Documents/Arduino. Use the sketchbook location shown in Settings or Preferences.
7. Create the sketchbook libraries folder if it is missing. Run these commands in that folder. For the usual macOS sketchbook:

mkdir -p ~/Documents/Arduino/libraries
cd ~/Documents/Arduino/libraries
git clone https://github.com/cearto/ThingPlusBLEOSC.git

If the sketchbook location is different, create libraries in that sketchbook if the folder is missing, then run git clone https://github.com/cearto/ThingPlusBLEOSC.git in that libraries folder.

8. Quit Arduino IDE and open it again.
9. Connect the micro-USB cable to the ESP32 and the computer. Then select the board SparkFun ESP32 Thing Plus and the port for that cable.
10. Upload.
11. Open Serial Monitor. Set the baud rate to 115200.
12. Find this line.

2P1V_Adafruit initialized. Send rheo/api for supported commands.

When the Qwiic Button is found, the monitor also prints:

Qwiic button ready (1-click=REP, 2-click=suck, hold=blow).

The initialized line above is the one startup check. If that output was missed, one reset is the retry. PCB and portable builds press the board reset button here, with Serial Monitor already open at 115200, and read the line once. RheoBoardOTS - DIY reads it once in the startup check below, with the 12 V adapter unplugged from the wall.

If Serial Monitor prints a line that begins with PneumaticSystem:, stop and recheck the board named in that line. RheoBoardOTS - DIY wire-change actions for those lines are in the startup check below. PCB and portable builds do not use that section.

Check:

• The open folder is named 2P1V_Adafruit and contains the .ino, .h, and .cpp files
• USB was connected before its port was selected
• The board is SparkFun ESP32 Thing Plus
• Serial Monitor baud is 115200
• The monitor shows 2P1V_Adafruit initialized. Send rheo/api for supported commands.
• The monitor does not show PneumaticSystem: HAL init failed (seesaw board and/or MPRLS not found).

RheoBoardOTS - DIY builders continue at RheoBoardOTS - DIY startup check.

RheoBoardOTS - DIY startup check

This check is for the RheoBoardOTS - DIY route only. PCB and portable builds finish at the install checklist above. They do not use the adapter steps in this section.

On the DIY panel, these steps do not connect a battery, and the 12 V adapter does not power the ESP32. USB powers the board. Leave the battery disconnected. Leave the 12 V adapter unplugged from the wall. Leave USB connected.

The startup line in Install is the one successful check. When that line was already visible, the check is complete. When the startup output was missed, press the board reset button with Serial Monitor already open at 115200 and the 12 V adapter unplugged from the wall, and read the line once.

If a startup line names a missing board, follow that row. Those actions remove power before a wire change.

Message	Next action
Qwiic button not found (required for documented button controls; continuing without it).	Recheck the Qwiic Button. The sketch continues. Unplug the adapter from the wall, disconnect USB, and leave the battery disconnected before you change a wire.
PneumaticSystem: ATtiny1616 seesaw board not found on Qwiic bus.	Stop. Unplug the adapter from the wall, disconnect USB, and leave the battery disconnected. Recheck the seesaw on the Qwiic chain.
PneumaticSystem: MPRLS pressure sensor not found on Qwiic bus.	Stop. Unplug the adapter from the wall, disconnect USB, and leave the battery disconnected. Recheck the MicroPressure sensor on the Qwiic chain.
PneumaticSystem: HAL init failed (seesaw board and/or MPRLS not found).	Stop. The sketch does not continue. Unplug the adapter from the wall, disconnect USB, and leave the battery disconnected, then recheck the Qwiic chain.

Check:

• Serial Monitor showed 2P1V_Adafruit initialized. Send rheo/api for supported commands.
• The monitor does not show PneumaticSystem: HAL init failed (seesaw board and/or MPRLS not found).
• USB is connected, the battery is disconnected, and the adapter is unplugged from the wall

RheoBoardOTS - DIY route only. When this startup check passes, return to Assembly Step 05: Check power and idle behavior. Leave USB connected. Leave the adapter unplugged from the wall.

I2C addresses

Board	I2C address
SparkFun ESP32 Thing Plus	Qwiic host
SparkFun Qwiic Button	0x6F
SparkFun Qwiic MicroPressure	0x18
Adafruit ATtiny1616 seesaw	0x49

REP timing

A REP in this sketch runs baseline, then retract, then extrude, then relax, inside a 1200 ms window (REP_TIME in RheoSystem.h). The relax portion is the time left in that window after baseline, valve settle, retract, and extrude.

At startup the sketch turns both pumps off and sets the valve output low.

Serial REP runs one REP. The BLE address for one REP is /rheo/rep. The BLE address for three REPs is /rheo/rep/triad.

The default interval is 500 ms (REP_INTERVAL_MS). In a triad, that value is the gap after one REP finishes, before the next REP starts.

After the first measurement

These commands run the pumps or the valve.

The serial parser treats a newline or a carriage return as the end of a command. In Serial Monitor, set the line ending to Newline, Carriage return, or Both NL & CR.

Command	Where	Effect
REP	USB serial	One REP. This runs the pumps.
STOP	USB serial	Abort a REP or a continuous pump test.
PUMP1 <pct>	USB serial	Run the vacuum pump until STOP.
PUMP2 <pct>	USB serial	Run the pressure pump until STOP.
/rheo/rep	BLE	One REP.
/rheo/rep/triad	BLE	Three REPs. After a REP finishes, /rheo/rep/interval is the gap before the next REP starts.
/rheo/stop	BLE	Abort the REP and cancel the triad.
One click	Qwiic Button	One REP.
Two clicks	Qwiic Button	Latch the vacuum pump. Two clicks again release it.
Hold	Qwiic Button	Momentary pressure until you release.

Defaults

These values are held in RAM. They reset when power is removed.

Setting	BLE address	Default
Pull power	/rheo/rep/pull/power	54%
Pull time	/rheo/rep/pull/time	315 ms
Push power	/rheo/rep/push/power	100%
Push time	/rheo/rep/push/time	345 ms
Push ramp start	/rheo/rep/push/ramp/start	40%
Push ramp time	/rheo/rep/push/ramp/time	300 ms
Baseline time	/rheo/rep/baseline/time	420 ms
Interval	/rheo/rep/interval	500 ms after a REP finishes
Sample period	/rheo/sense/rate	10 ms

Push power of 100% is the sketch default. On the DIY panel it is not a confirmed voltage at the pump.

When you read or set one of these over BLE, Serial Monitor prints the address and the value, for example /rheo/rep/pull/power=54.

/db/save is sent when a REP recording ends. It does not save these settings.

USB serial prints pressure as #S,<ms>,<Pa> while a recording or a pump test is running. The same samples go out on BLE as /rheo/sense/air, in pascals, while a REP recording is running. The sketch does not print pressure while it is idle.