StepScreen

StepScreen is the control platform behind Neurotech Hub instruments — a compact board and software stack that pairs a sharp OLED display and rotary encoder with precision stepper motion, onboard storage, and lab-ready I/O.

Built for hands-on neuroscience and behavioral setups, StepScreen powers applications like syringe pumps and rodent treadmills: set parameters on-device, start a run with a single button, and keep the experiment moving without a laptop in the cage room. The same hardware also supports load cells, beam detectors, indicator lights, and battery-aware field use.

What you get:

On-device UI — 1.3" OLED with encoder and dedicated Back / Select / Confirm controls for clear, gloved-hand menus
Motion control — quiet, accurate stepper driving for pumps, belts, and custom actuators
Experiment I/O — sensors, LEDs, external triggers, and microSD logging on a familiar Feather-class footprint
Ready-to-run apps — example firmware for syringe delivery and treadmill sessions you can deploy or adapt

Open-source firmware and pin maps live below for builders who want to extend or rebrand the platform.

Library structure

Source lives under src/ (Arduino's modern layout). Only files in src/ are compiled as library code, which keeps the root clean as the library grows:

StepScreen/
├── library.properties
├── README.md
├── StepScreenPins_override.example.h   # pin override template (not compiled)
├── src/                                # library source
│   ├── StepScreen.h                    # main include
│   └── ...
└── examples/
    ├── ScreenTest/
    └── BasicUI/

Sketches still use #include <StepScreen.h> — the IDE adds src/ to the include path automatically.

Hardware

Board: ATSAMD21G18 @ 48 MHz, 3.3V logic (select "Adafruit Feather M0" in the Arduino IDE)
Display: 1.3" 128x64 monochrome OLED, SH1106 driver, I2C at 0x3C on Wire (pins 20/21)
RTC: PCF8523 on the same I2C bus at 0x68 (Adalogger onboard RTC; optional)
Encoder: EC11, 20 pulses / 20 detents, with push switch
Buttons: independent back and confirm buttons on the module

Dependencies

Install via the Arduino Library Manager:

Adafruit SH110X
Adafruit GFX Library
Adafruit BusIO
AccelStepper (used by StepScreenStepper)
TMCStepper (used by StepScreenTMC2209)
RTClib (used by StepScreenRTC)

Pin map

Screen module defaults (from StepScreenPins.h):

Symbol	Default pin	Module signal
`PIN_ENC_A`	12	SCREEN_TRA (encoder quadrature A)
`PIN_ENC_B`	10	SCREEN_TRB (encoder quadrature B)
`PIN_BTN_BACK`	11	SCREEN_BAK (back button)
`PIN_BTN_CONFIRM`	A0	SCREEN_CONFIRM (confirm button)
`PIN_BTN_PUSH`	A3	SCREEN_PUSH (encoder shaft push)

Board I/O (from StepScreenBoard.h):

Symbol	Default pin	Notes
`PIN_SD_CS`	4	microSD chip select
`PIN_SD_CD`	7	card detect (`STEPSCREEN_SD_CD_INSERTED`, default LOW)
`PIN_LED_GREEN` / `PIN_USER_LED1`	13	green user LED (D13)
`PIN_LED_RED` / `PIN_USER_LED2`	A1	red user LED
`PIN_EXT_LED`	A2	external LED via N-MOSFET (220 Ω gate, 10 kΩ pulldown); HIGH = ON
`PIN_BEAM_DET`	A4	photodetector; external pull-up — use `INPUT`, no internal pullup
`PIN_AUX_IN`	A5	general-purpose digital input
`PIN_VBAT`	A7 (pin 9)	battery voltage divider (reads VBAT/2)
`PIN_I2C_SDA` / `PIN_I2C_SCL`	20 / 21	Wire
`STEPSCREEN_RTC_I2C_ADDR`	0x68	PCF8523 RTC (optional)
`PIN_SWCLK` / `PIN_SWDIO`	PA30 (30) / PA31 (31)	silkscreen SWCLK / SWDIO — HX711 SCK/DT
`PIN_HX711_SCK` / `PIN_HX711_DT`	PA30 / PA31	aliases of `PIN_SWCLK` / `PIN_SWDIO`

Optional helpers: #include <StepScreenIO.h> for output registry and input sampling; #include <StepScreenIODisplay.h> to render I/O status on the OLED; #include <StepScreenSD.h> for microSD mount/read/write with card-detect hot-plug; #include <StepScreenHX711.h> for HX711 load cell on SWD pads; #include <StepScreenStore.h> for small EEPROM blob persistence on SAMD21; #include <StepScreenRTC.h> for PCF8523 date/time. See the IOTest, LoadCellTest, Treadmill, Truss, and SyringePump examples.

TMC2209 stepper (step/dir + half-duplex UART, from StepScreenBoard.h):

Symbol	Default pin	Notes
`PIN_MOTOR_STEP`	5	STEP pulse
`PIN_MOTOR_DIR`	6	direction
`PIN_MOTOR_EN`	9	~EN, active LOW (LOW = enabled)
`PIN_MOTOR_UART_RX`	0	D0 — half-duplex UART node with TX
`PIN_MOTOR_UART_TX`	1	D1 — 1kΩ in series to TMC PDN_UART

MS1 and MS2 are tied HIGH on the module (UART address 0b11). Runtime microstep count is configured over UART via StepScreenTMC2209, not the strap pins. STEPSCREEN_MOTOR_MICROSTEPS defaults to 128; STEPSCREEN_MOTOR_STEPS_PER_REV is derived (200 full steps × microsteps). Override in a sketch before includes:

#define STEPSCREEN_MOTOR_MICROSTEPS 64
#include <StepScreenStepper.h>

microSD (`StepScreenSD`)

The Adalogger exposes SPI chip select on pin 4 and a mechanical card-detect switch on pin 7. On the StepScreen board the CD pin reads LOW when a card is inserted (INPUT_PULLUP). Stock Adalogger pinouts use the opposite polarity — add #define STEPSCREEN_SD_CD_INSERTED HIGH before #include <StepScreenSD.h> if needed.

#include <StepScreenSD.h>

StepScreenSD sd;
sd.begin();          // optional cs/cd pins; defaults PIN_SD_CS / PIN_SD_CD

void loop() {
  sd.update();       // required for hot-plug
  if (sd.isReady()) {
    sd.appendLine("/log.txt", "sample");
  }
}

See IOTest for automatic output walk, live dashboard, and SD self-test on mount.

SD timestamps: Arduino SD.h does not wire the RTC into FAT directory entry timestamps, so files may show incorrect dates in the OS. For correct FAT times, a future change would need SdFat with FsDateTime::setCallback. Until then, prefix log lines with StepScreenRTC::formatLogTimestamp() in the file content itself.

RTC (`StepScreenRTC`)

The Adalogger PCF8523 shares Wire with the OLED at STEPSCREEN_RTC_I2C_ADDR (default 0x68). Call begin() after the display (or any other code that starts I2C). syncFromBuildTimeIfNeeded() sets the clock from the firmware build stamp (__DATE__ / __TIME__) when the RTC is unset, lost power, or behind the compile time.

#include <StepScreenRTC.h>

StepScreenRTC rtc;
rtc.begin();                        // after screen.begin()
rtc.syncFromBuildTimeIfNeeded();    // sets from __DATE__/__TIME__ when needed

char header[12];
rtc.formatInfoBar(header, sizeof(header));
screen.drawInfoBar(header);

If the RTC is absent, formatInfoBar() returns "-- --:--" and the sketch continues normally. See Treadmill and SyringePump for live date/time in the info bar.

HX711 load cell (`StepScreenHX711`)

The StepScreen board routes the HX711 to the SWD pads (PA30/PA31), silkscreened CLK and DIO. These pins are not in the stock Feather M0 Arduino pin map, so StepScreenHX711 bit-bangs the HX711 protocol via SAMD PORT registers. SWD hardware debug is unavailable while the load cell is connected.

#include <StepScreenHX711.h>

StepScreenHX711 scale;
scale.begin();
if (scale.verify()) {
  scale.set_scale(420.0f);   // raw counts per gram — calibrate once
  scale.tare(10);
  float grams = scale.get_units(3);
}

See LoadCellTest for serial measure mode (200 ms) and CAL interactive calibration. See Truss for on-device calibration saved to SD (/TRUSS.CAL) and closed-loop cable tension control.

Non-blocking reads: poll is_ready() and call get_units(1) when DOUT is low — one conversion per call, typically ~10 Hz (80 Hz if the HX711 module RATE pin is tied high).

All buttons are read active LOW with internal pullups; no external resistors are needed. Swap PIN_ENC_A/PIN_ENC_B to flip the encoder's rotation sign.

Overriding pins

Nothing in the library needs to be edited. Define the pins you want to change in your sketch before including the library:

#define PIN_ENC_A 6
#define PIN_BTN_BACK 5
#include <StepScreen.h>

Alternatively (PlatformIO or any build where your project folder is on the include path), copy StepScreenPins_override.example.h into your project as StepScreenPins_override.h and edit it there -- StepScreenPins.h picks it up automatically.

Screen layout

The 128x64 panel is divided into fixed zones (constants in StepScreenLayout.h):

x=0                  x=100    x=127
+---------------------+--------+  y=0
| Info bar (title)    |   Back |  y=0..7
+---------------------+--------+  y=8
|                     |        |
| Content (100x56)    |    Sel |  <- encoder push
|                     |        |
|                     |     OK |  <- confirm
+---------------------+--------+  y=63

The action column labels mirror the physical button positions: back at the top right, encoder push in the middle, confirm at the lower right. Active labels are drawn inverted.

Quick start

#include <StepScreen.h>

StepScreen screen;
int32_t counter = 0;

void setup() {
  screen.begin();

  // --- STEPSCREEN ENCODER ISR SETUP (copy into setup()) ---
  attachInterrupt(digitalPinToInterrupt(PIN_ENC_A),
                  StepScreenInput::handleEncoderISR, CHANGE);
  attachInterrupt(digitalPinToInterrupt(PIN_ENC_B),
                  StepScreenInput::handleEncoderISR, CHANGE);
  // --- END STEPSCREEN ENCODER ISR SETUP ---
}

void loop() {
  counter += screen.input().getEncoderDelta();

  StepScreenDisplay &d = screen.display();
  d.clearDisplay();
  d.drawInfoBar("My App");
  d.drawActionColumn(screen.input().readBack(),
                     screen.input().readPush(),
                     screen.input().readConfirm());
  d.setCursor(0, 16);
  d.print(counter);
  d.display();
}

Encoder interrupts (must live in the sketch)

The library provides the ISR body (StepScreenInput::handleEncoderISR) but never calls attachInterrupt() itself, so each sketch stays in control of its interrupt configuration. Every new sketch must copy the marked block above into setup(), after screen.begin(). The macro STEPSCREEN_ATTACH_ENCODER_ISRS(); from StepScreenInterrupts.h expands to the same block if you prefer a one-liner.

Rotation is then consumed in the loop:

input().getEncoderDelta() -- detents since the last call (signed)
input().getEncoderCount() -- absolute detent count since begin()

Buttons are polled and debounced (no interrupts needed): readBack() / readPush() / readConfirm() return the held state, and pollButtons() returns edge-detected press events (STEPSCREEN_EVT_BACK, STEPSCREEN_EVT_PUSH, STEPSCREEN_EVT_CONFIRM).

SAMD21 note: pins 12 and 10 use separate EXTINT lines, so the default mapping is safe. If you remap the encoder, the two pins must not share an EXTINT line.

TMC2209 UART: StepScreenTMC2209

Half-duplex UART on D0/D1 configures the BIGTREETECH TMC2209 before motion. Wiring:

D1 (TX) --[1kΩ]--+-- TMC PDN_UART
D0 (RX) ---------+
TMC TX pad: NC

Call configureForStepDir() before enable() on StepScreenMotor or StepScreenStepper:

#include <StepScreenTMC2209.h>
#include <StepScreenStepper.h>

StepScreenTMC2209 tmc;
StepScreenStepper stepper;

void setup() {
  tmc.begin();
  if (!tmc.verify()) {
    StepScreenTMC2209::printWiringHelp();
    return;
  }
  tmc.configureForStepDir();           // uses STEPSCREEN_MOTOR_MICROSTEPS
  // tmc.configureForStepDir(64);      // optional per-call override
  stepper.begin();                     // or stepper.beginWithDriver(tmc);
  stepper.enable();
}

Call	Purpose
`begin()`	Start Serial1 + driver
`verify()`	Confirm UART link (`version()` == 0x21)
`configureForStepDir(microsteps, mA)`	UART mode, chopper, current, microsteps
`driver()`	Raw `TMC2209Stepper` for advanced register access
`printWiringHelp()`	Serial wiring checklist

See DriverTest (Troubleshooting) for a full UART bring-up sequence.

TMC2209 step/dir: StepScreenMotor

StepScreenMotor generates STEP/DIR/~EN pulses only — no UART. Use after StepScreenTMC2209::configureForStepDir():

#include <StepScreenMotor.h>

StepScreenMotor motor;

void setup() {
  motor.begin();
  motor.enable();
  motor.moveStepsSigned(STEPSCREEN_MOTOR_STEPS_PER_REV / 10);
}

void loop() {
  motor.setSpeed(400.0f);  // steps/sec; sign sets direction
  motor.runSpeed();        // call every loop() iteration
}

Call	Purpose
`begin()`	Configure STEP/DIR/~EN pins; driver starts disabled
`enable()` / `disable()`	Toggle ~EN (active LOW)
`setDirection(fwd)` / `step()`	Set DIR and issue one microstep pulse
`moveSteps(n, delayUs)`	Blocking move in current direction
`moveStepsSigned(n, delayUs)`	Blocking move; sign sets direction
`setSpeed(stepsPerSec)` / `runSpeed()`	Non-blocking continuous motion
`getPosition()` / `resetPosition()`	Signed microstep counter
`getStepCount()`	Total pulses issued since `begin()`

Application motion: StepScreenStepper (AccelStepper)

For application motion — acceleration, non-blocking moves, speed presets — use StepScreenStepper, a thin wrapper around AccelStepper in DRIVER mode with the board's pins and ~EN polarity preconfigured. Configure UART first via StepScreenTMC2209; StepScreenMotor remains the raw pin-level option for hardware bring-up.

#include <StepScreenTMC2209.h>
#include <StepScreenStepper.h>

StepScreenTMC2209 tmc;
StepScreenStepper stepper;

void setup() {
  tmc.begin();
  tmc.verify();
  tmc.configureForStepDir();
  stepper.begin();          // driver starts disabled
  stepper.enable();
  stepper.moveSigned(STEPSCREEN_MOTOR_STEPS_PER_REV);
}

void loop() {
  stepper.run(); // non-blocking; call every loop() iteration
}

Call	Purpose
`begin()`	Configure pins + defaults; UART must be configured first
`beginWithDriver(tmc)`	`verify()` + `configureForStepDir()` + `begin()`
`enable()` / `disable()`	Toggle ~EN; `disable()` also cancels pending motion
`jogSteps(n)` / `moveSigned(n)`	Relative moves (poll `run()` until done)
`run()`	Step generator; returns `true` while a move is pending
`setSpeedPreset(p)` / `nextSpeedPreset()`	Low / Med / Fast presets (`STEPSCREEN_SPEED_*_SPS`, overridable)
`setMaxSpeed(sps)` / `setAcceleration(sps2)`	Direct control
`isRunning()` / `stop()` / `currentPosition()`	Motion state
`raw()`	Underlying `AccelStepper` for advanced use

Preset defaults: Low 200, Med 800, Fast 2000 microsteps/sec; acceleration 4000 microsteps/sec². Override any of them before including the header (e.g. #define STEPSCREEN_SPEED_FAST_SPS 4000.0f).

Menu navigation: StepScreenNav

StepScreenInput's 20 ms debounce handles switch bounce, but menus need more: a press that triggers a screen change must not also fire on the new screen, and a held button must not repeat. StepScreenNav layers both guarantees on top of the raw input:

Transition settle — all button edges are discarded for STEPSCREEN_NAV_SETTLE_MS (default 250 ms) after enterScreen().
Release-before-accept — after a press is delivered, nothing more is accepted until every button has been released.

#include <StepScreenNav.h>

StepScreenNav nav;

void setup() {
  // after screen.begin() ...
  nav.begin(&screen.input());
}

void changeScreen() {
  nav.enterScreen(); // call on EVERY screen/mode change
}

void loop() {
  uint8_t ev = nav.pollNavEvents();       // filtered STEPSCREEN_EVT_* bitmask
  int32_t enc = nav.consumeEncoderDelta(); // flushed by enterScreen()
  // nav.readBack()/readPush()/readConfirm() for UI highlights only
}

Call pollNavEvents() exactly once per loop — it consumes the underlying edge state.

Examples

ScreenTest -- display validation followed by an interactive control check (encoder + all three buttons). Run this first on new hardware.
BasicUI -- interactive demo: the encoder drives a counter, and each button highlights its action-column label. Includes the encoder ISR block.
MotorTest -- TMC2209 UART verify + step/dir exercise without a motor connected. Blocking and non-blocking moves with Serial reporting; green LED blinks on each STEP pulse.
DriverTest (Troubleshooting) -- UART bring-up: version check, microstep register sweep, physical move at STEPSCREEN_MOTOR_MICROSTEPS.
IOTest -- auto-walks each board output solo while a single dashboard shows inputs, encoder, VBAT, and SD status. SD self-test runs automatically when a card mounts.
LoadCellTest -- HX711 load cell on SWCLK/SWDIO (CLK/DIO). Measure mode prints grams every 200 ms; type CAL for interactive tare/scale calibration over Serial.
SyringePump -- three-screen pump controller built on StepScreenNav + StepScreenStepper. Home (motor off), Adjust (encoder jogs the motor; OK cycles Low/Med/Fast speed), Run (send a signed step count over Serial at 115200 — one revolution equals STEPSCREEN_MOTOR_STEPS_PER_REV). Demonstrates the menu debounce pattern.
Treadmill -- rodent treadmill controller. Home shows speed (cm/s) and timeout (minutes) with the edited metric inverted (Back toggles Spd/Time, Sel toggles Fwd/Rev, encoder adjusts). Run ramps the belt to speed via setSpeed()/runSpeed(), counts down, then disables the motor and blinks DONE. Speed→steps mapping is a placeholder (STEPSCREEN_TREADMILL_SPS_PER_CMS).
Truss -- closed-loop cable tension controller for a load-cell inline with a stepper spool. Home shows live load (grams) or NO CAL; encoder sets target load (0–500 g). Startup warns if stepper (12 V/TMC), load cell, or SD card is missing; Home footer lists anything still offline. Cal requires load cell + SD: two-step tare then known-weight calibration saved to /TRUSS.CAL. Run requires stepper, load cell, SD, and valid cal. Control uses hysteresis (TRUSS_STOP_G / TRUSS_START_G), continuous creep at TRUSS_APPROACH_SPS in the mid band, and a few-step nudge (TRUSS_NUDGE_STEPS inside TRUSS_NUDGE_G); farther out, speed scales with load error (TRUSS_GAIN_SPS_PER_G, capped at TRUSS_SPS). Commands update on each HX711 sample; an EMA filter (TRUSS_FILTER_ALPHA) smooths readings. Prefer an 80 Hz HX711 RATE jumper (many modules ship at 10 Hz). Direction-timeout faults only apply far from target when error is not improving. A TC3 step ISR drives pulses while a 5 ms ramp (TRUSS_RAMP_MS) smooths speed changes. Set TRUSS_WIND_SIGN if wind/unwind is reversed. Serial telemetry every TRUSS_DEBUG_MS (0 to disable). Session logging (SD + RTC) writes /YYYYMMDD/HHMMSS.CSV with columns datetime,event,target_load_g,actual_load_g and events begin / measure (~1 Hz, 2-minute RAM buffer) / end / fault; a full buffer briefly holds the motor (enabled, zero speed) while flushing. HOLD pauses the loop and timer; overload, step-limit, and direction-timeout faults stop the motor.

API summary

Call	Purpose
`screen.begin()`	Initialize display + inputs (returns `false` if the OLED is missing)
`screen.display()`	The `StepScreenDisplay` (full GFX API + helpers below)
`screen.input()`	Buttons + encoder
`drawInfoBar(title, highlightBack)`	Inverted top bar with left-aligned title
`drawActionColumn(back, push, confirm)`	Right-justified Back/Sel/OK labels
`drawActionColumn(labels, back, push, confirm)`	Per-screen labels via `StepScreenActionLabels`; `nullptr` leaves that slot blank (unavailable). Labels longer than 4 chars are truncated
`clearContentArea()`	Clear only the content zone, cursor to its origin
`drawLayoutGuides()`	Zone borders + corner markers (for testing)

Layout helpers draw at text size 1; set your own size afterwards for content.

Navigation Menu

Uh oh!

Repository files navigation

StepScreen

Library structure

Hardware

Dependencies

Pin map

microSD (`StepScreenSD`)

RTC (`StepScreenRTC`)

HX711 load cell (`StepScreenHX711`)

Overriding pins

Screen layout

Quick start

Encoder interrupts (must live in the sketch)

TMC2209 UART: StepScreenTMC2209

TMC2209 step/dir: StepScreenMotor

Application motion: StepScreenStepper (AccelStepper)

Menu navigation: StepScreenNav

Examples

API summary

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
examples		examples
src		src
.gitignore		.gitignore
README.md		README.md
StepScreenPins_override.example.h		StepScreenPins_override.example.h
library.properties		library.properties

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

StepScreen

Library structure

Hardware

Dependencies

Pin map

microSD (StepScreenSD)

RTC (StepScreenRTC)

HX711 load cell (StepScreenHX711)

Overriding pins

Screen layout

Quick start

Encoder interrupts (must live in the sketch)

TMC2209 UART: StepScreenTMC2209

TMC2209 step/dir: StepScreenMotor

Application motion: StepScreenStepper (AccelStepper)

Menu navigation: StepScreenNav

Examples

API summary

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

microSD (`StepScreenSD`)

RTC (`StepScreenRTC`)

HX711 load cell (`StepScreenHX711`)