FilMachine Mainboard

FilMachine — Automated Film Development Machine

FilMachine is an automated film processing machine designed for photographic film development. It handles the entire process: chemical baths, water rinses, temperature regulation, and motor-driven film agitation — all controlled through a 4.3" color touchscreen display.

The project includes a desktop simulator (SDL2 + LVGL) that reproduces the full touchscreen UI on macOS/Linux (a Windows build is produced by CI), enabling rapid development and testing without physical hardware, plus an automated test suite (19 suites). A Flutter companion app connects via WebSocket and provides full remote control from any mobile device on the same network.

The interface is bilingual (English / Italiano) — selectable from Settings, applied with an automatic reboot — and every boot writes a diagnostic log to the SD card (/log/boot_NNNN.txt), including the crash summary of the previous run when the firmware panicked.

The repository also holds the mechanical side of the project: the 3D-printed film reel auto-loader (bench prototype v1, for 135 and 120 film) — see Film Reel Auto-Loader.

Table of Contents

1. What is FilMachine?
2. Project Architecture
3. Directory Structure
4. Building the Project
5. Running the Simulator
6. Running the Tests
7. WebSocket Server & Remote Control
8. Flutter Companion App
9. User Interface Guide
10. Firmware Update (OTA)
11. Hardware Specifications
12. Bill of Materials (Components)
13. Film Reel Auto-Loader (3D-Printed Prototype)
14. Diagnostics & Bring-up Page
15. Build-time Switches
16. Configuration & Persistence
17. Language / Localization
18. SD Boot & Crash Log
19. Typical Workflows
20. Developer Quick Reference
21. Authors

What is FilMachine?

FilMachine takes the guesswork out of developing photographic film at home or in a small lab. Instead of manually timing each step, pouring chemicals by hand, and constantly checking the thermometer, FilMachine automates everything. You load your film in the developing tank, select a process, and press Start. The machine takes care of the rest: filling the right chemical at the right time, keeping the temperature stable, rotating the film at the correct speed, rinsing between steps, and alerting you when the process is complete.

It supports both color negative (C41, E6) and black & white film development workflows, with full customization of every parameter.

Project Architecture

The project has a dual-target build system that produces ESP32-P4 firmware or a native desktop application from the same codebase. The only supported hardware board is the Guition JC4880P433 (ESP32-P4).

Technology Stack

How the Simulator Works

The simulator replaces all hardware-specific code with a stub layer that provides compatible implementations:

• FatFS stubs map firmware paths (e.g., /FilMachine.json) to files inside an sd/ subdirectory of the directory the simulator is launched from, so read/write operations work transparently.
• FreeRTOS stubs provide working queue implementations (xQueueCreate, xQueueSend, xQueueReceive) using simple circular buffers. Task creation is a no-op since there are no real threads — instead, the main loop drains the system queue every frame.
• Hardware stubs (GPIO, I2C, SPI, solenoid driver, motor, temperature) are either no-ops or printf-based logging functions. Temperature readings come from a simple thermal model that simulates heating/cooling.
• OTA stubs simulate the firmware update flow with a progress timer (0→100%) and fake IP address, allowing full UI testing without real hardware.
• LVGL's SDL2 driver provides the display backend and mouse input, which simulates the capacitive touchscreen.

The key architectural principle is that all UI code is shared 1:1 between firmware and simulator. Pages, elements, event handlers, and business logic are identical — only the hardware abstraction layer changes.

Directory Structure

FilMachine_Reworked/
│
├── main/                          # Core source (shared with ESP32 firmware)
│   ├── include/
│   │   └── FilMachine.h           #   Main header — all structs, enums, constants, prototypes
│   ├── FilMachine.c               #   ESP32 entry point — board-conditional display/touch init
│   ├── accessories.c              #   Utilities — linked lists, deep copy, config I/O, keyboard
│   ├── lang.c                     #   EN/IT string table (generated by scripts/gen_lang.py)
│   ├── sd_log.c                   #   Boot/crash logger on SD (/log/boot_NNNN.txt, firmware only)
│   ├── mini_json.c                #   Dependency-free JSON parser for the config file
│   ├── ota_update.c               #   OTA firmware update (SD card + Wi-Fi web server)
│   ├── ws_server.c                #   WebSocket server for Flutter companion app
│   ├── film_loader.c              #   Film loading cycle (wind, stall detect, cut, tail) — Tools → Load film
│   └── ui_profile.c               #   Centralized UI layout constants (800×480)
│
├── c_pages/                       # UI pages (screens)
│   ├── page_splash.c              #   Splash screen — standard, random, and custom modes with
│   │                              #     10 palettes, 6 shape styles, 9 title fonts, PRNG engine
│   ├── page_menu.c                #   Tab bar navigation (Processes / Settings / Tools)
│   ├── page_processes.c           #   Process list with filtering
│   ├── page_processDetail.c       #   Process creation & editing
│   ├── page_stepDetail.c          #   Step creation & editing with validation
│   ├── page_settings.c            #   Machine settings, grouped in sections (process, rotation, liquids, display, system)
│   ├── page_tools.c               #   Maintenance tools, import/export, statistics, OTA

Building the Project

Prerequisites

macOS:

brew install cmake sdl2 pkg-config

Ubuntu / Debian:

sudo apt install cmake libsdl2-dev pkg-config build-essential

LVGL v9.5.0 is automatically cloned from GitHub on the first build if not present (the firmware pulls the same version through the ESP-IDF component manager, lvgl/lvgl ~9.5.0).

Windows: there is no local recipe; the GitHub Actions workflow .github/workflows/windows-sim.yml builds filmachine_sim.exe with MSYS2/MinGW on every push to main that changes more than the documentation (or on demand from the Actions tab) and uploads it — with its runtime DLLs and a freshly generated sd/ config — as the filmachine-sim-windows artifact.

Build the Simulator

mkdir -p build800 && cd build800
cmake ..
make filmachine_sim

The simulator opens an 800×480 window matching the JC4880P433 physical panel in landscape orientation.

Build the Tests

mkdir -p build800 && cd build800
cmake ..
make filmachine_test
./filmachine_test

Build the Firmware

Requires the ESP-IDF toolchain (v5.5.x or later) installed and configured.

Important: run idf.py from the project root, not from build800/.

cd FilMachine_Reworked
. $HOME/esp/esp-idf-v5.5/export.sh     # Must be ESP-IDF 5.5.x or later

# First-time setup: set target to esp32p4 (creates sdkconfig from defaults)
idf.py set-target esp32p4

# Build — board is auto-detected from IDF_TARGET
idf.py build

The main/CMakeLists.txt automatically sets -DBOARD_JC4880P433. No manual -DCMAKE_C_FLAGS flag is needed (passing -D CMAKE_C_FLAGS="-DBOARD_JC4880P433" is harmless but redundant).

See COMMANDS.md for the canonical quick reference: simulator + board build, flash/monitor, generating and copying the SD config, version bumping and cleanup.

Flash and monitor

The firmware binary is produced at build/FilMachine.bin. To flash it directly to a connected board:

idf.py flash

Or use the all-in-one helper (written for macOS), which sets the target if needed, patches sdkconfig for the P4 board, increments the build number in version.txt, builds, looks for the serial port, flashes and opens the monitor:

./flash_p4.sh

flash.sh and setup.sh are leftovers of the earlier ESP32-S3 workflow (they copy sources between the old FilMachine_Simulator_v2 folder and the FilMachine_Pete repository). They are not used for the ESP32-P4 and can be ignored.

P4 note: the bootloader offset on ESP32-P4 is 0x2000 (different from ESP32-S3's 0x0). This is handled automatically by idf.py when the target is set correctly.

To check the firmware size (useful for verifying OTA partition fit):

idf.py size

Running the Simulator

Simulator UI debug overlay

The simulator includes a built-in UI inspection mode to speed up layout tuning.

• Press F2 to enable or disable the overlay.
• When enabled, moving the mouse over the UI shows:
  • the resolved component name when available (for example gui.page.processes.newProcessButton)
  • the object position (x, y)
  • the object size (w, h)
• While the overlay is enabled, right click dumps the hovered object to the terminal/console.

This is especially useful when adjusting coordinates inside ui_profile.c, because you can identify the exact widget and immediately see its current geometry in the simulator.

cd build800
./filmachine_sim

The simulator opens an 800×480 window that reproduces the exact touchscreen interface. Use the mouse to simulate touch input (click = tap, click-drag = swipe/scroll).

What works in the simulator

• Full UI navigation (all pages, popups, dialogs)
• Splash screen with live preview popup, 10 palettes, 6 shape styles, 9 custom fonts
• Process creation, editing, duplication, deletion
• Step management with swipe gestures
• Settings with slider/switch/radio controls
• Filter and search functionality
• Configuration save/load (reads/writes sd/FilMachine.json)
• Export/Import (backup to sd/FilMachine_Backup.json)
• Drain machine with animated tank-level bars and relay management
• Empty chemistry (machine v7): C1, C2 or C3 into its recovery bottle through the pump and the recovery outlet, line washed before and after, with a source → tank → bottle animation
• Clean machine with per-container rinse cycles and arc progress
• Self-check diagnostic wizard with 8-phase hardware test simulation (temp sensors, pump, heater, valves, containers, motor)
• OTA update UI (SD card check + Wi-Fi popup with simulated IP/PIN/progress)
• Simulated temperature readings with heater model and calibration offset
• Persistent alarm sound (SDL audio 880Hz beep, repeats every 10s until dismissed)
• Drain/fill overlap processing (adjusts step timing based on overlap percentage)
• Machine statistics persistence (saved in config file, survives restart)
• Temperature sensor calibration (Tune button calculates and applies offset)
• Console logging of all system actions ([SIM] sysAction: ...)
• WebSocket server on port 81 for Flutter companion app remote control
• Full remote process start, stop, and checkup advance via WebSocket
• Remote CRUD for processes and steps (create, edit, delete from Flutter)

What is simulated (no real hardware)

• Temperature sensors return simulated values (20°C ambient, gradual heating/cooling)
• Motor control outputs to console only
• Relay switching outputs to console only
• OTA writes to a fake partition (progress simulated, no actual flash)
• Wi-Fi connection is simulated (fake IP 192.168.1.42, no real server)
• Reboot is a no-op (prints message)

Generating sample data

To generate realistic film development recipes:

python3 scripts/genFilMachineCFG.py --realistic --output build800/sd/

This creates config files with authentic C41, E6, and B&W development processes.

Running the Tests

cd build800
./filmachine_test

Results are displayed in the terminal and saved to test_results/test_results_YYYYMMDD_HHMMSS.txt.

Test Suites

The persistence tests verify that every field (process name, temperature, tolerance, film type, preferred flag, step names, durations, types, sources, discard flags) survives a full save-and-reload cycle.

Repeatable runs. Every run starts from the same data: the runner generates three test processes with the default settings and rewrites sd/FilMachine.json in the run directory, so a run never depends on what the previous one saved (steps used to pile up on the first process until the 30-step limit made the step tests fail). FM_TEST_ONLY=<suite>,<suite> runs only some suites (names after test_suite_, e.g. FM_TEST_ONLY=navigation,tools).

Timers run on real time. The SDL display makes LVGL read the real clock, so test_pump() processes events but does not advance LVGL timers; tests that wait for a 1 s timer sleep (see pump_real() in test_maintenance_remote.c).

Memory. The simulator and the tests use the C-library malloc for LVGL, like the board. With LVGL's own 256 KB pool the heap fragmented after a few suites, an allocation failed and LVGL's malloc assert spun forever, which looked like random hangs in the step tests. To check memory errors, build the runner with -fsanitize=address: AddressSanitizer then sees LVGL's allocations too.

WebSocket Server & Remote Control

The simulator and firmware include a built-in WebSocket server (ws_server.c) that enables remote control from the Flutter companion app or any WebSocket client. The server starts automatically and listens on port 81 at path /ws.

Supported Commands

All commands use JSON format: {"cmd":"command_name", ...params}.

The cleanTool* state fields include cleanToolProcessArc, cleanToolCycleArc and cleanToolPumpArc: the values of the three arcs exactly as drawn on the display's Clean popup, so the app draws the same picture.

set_setting keys — tempUnit, waterInlet, tempCalibOffset, chemCalibOffset, filmRotationSpeed, rotationInterval, random, persistentAlarm, autostart, drainFillOverlap, multiRinseTime, lineRinseEnabled, lineRinseTime, tankSize, pumpSpeed, chemCalibFillSecs, wbCalibFillSecs, chemistryVolume, invertPump, brightness, volume, splashDefault, splashRandom, splashPalette, splashShapeStyle, splashComplexity, language (0=EN, 1=IT — applied at next boot), screenOffMins (5/10/30, 0=never), wifiEnabled, loadSpeed (reel motor % while loading), cutterRestUs / cutterCutUs (servo pulse in µs at rest and at the top of the cut). All of these are also included in the broadcast state JSON.

Implementation Details

The server uses simple strstr() JSON parsing with no external library (no cJSON, no heap allocation for parsing). All commands that modify LVGL state are dispatched via lv_async_call() to ensure thread-safe UI updates. State changes are automatically broadcast to all connected clients.

Flutter Companion App

The companion app is a Flutter application that provides full remote control of FilMachine from any mobile device or desktop on the same network. It lives in its own repository, FilMachine_App (private); see its README for detailed documentation.

Keeping the two in step. The app mirrors the protocol implemented in main/ws_server.c. Whenever a field is added to build_state_json() or a key to set_setting, the app needs the same addition in its MachineState model, in MachineService._readSetting and in its Settings screen. The app release synced with firmware v0.0.0.54 parses all 71 state fields and sends all 17 commands; the only set_setting keys it never sends are the fill calibrations (read-only in the app) and wifiEnabled.

Key Features

• Device Discovery: Automatic mDNS discovery of FilMachine devices on the local network (_filmachine._tcp), plus manual IP/port entry
• Process Management: Create, edit, duplicate, and delete processes and steps — all changes sync to the machine in real-time
• Live Execution Monitoring: Real-time dashboard showing current step, progress bars, temperatures, tank fill status, and elapsed/remaining time
• Process Control: Start processes, advance through checkup phases, Stop Now / Stop After with confirmation dialogs
• Filtering: Client-side filtering by name, film type (B&W / Color), and preferred flag
• Statistics: View completed processes, stopped processes, total development time, cleaning cycles
• Settings: Full access to the machine settings, with the same sections as the display (Process, Film rotation, Pump and liquids, Display and sound, System) plus the app's own options
• Tools: A Tools tab laid out like the display's: Maintenance (Clean machine, Drain machine, Fill bath, Fill chem, Load film), Utilities (Export) and Software (Credits). Self-check, Import (it reboots the machine) and the firmware updates (the Wi-Fi one shows a PIN on the display on purpose) stay on the display; statistics, version and serial number are on the app's Dashboard
• Theme: Dark/light theme toggle with custom FilMachine color palette
• Persistent Connection: Remembers last successful connection for quick reconnect

Architecture

The app uses Provider for state management. A central MachineService (ChangeNotifier) maintains the WebSocket connection and holds the current MachineState — a data class with one field per key of the JSON state broadcast. All screens rebuild reactively when state changes.

User Interface Guide

The Processes Tab

This is where you manage your film development recipes. Each process is a sequence of steps the machine executes in order. The list shows each process with its name, total time, film type icon, and a star if marked as preferred.

• Process count: The section header dynamically shows the number of processes (e.g., "8 Processes"). The "+" button stays positioned right after the label text regardless of the count.
• Create: Tap "+" to add a new process
• Edit: Tap a process to open its detail view
• Duplicate: Swipe left to reveal the duplicate button
• Delete: Open the detail, tap the trash icon
• Filter: Tap the filter icon to search by name, film type, or preferred status. The filter icon turns green when a filter is active, and returns to white when reset.

Working with Steps

Each process contains steps. A step represents one phase: "Developer", "Stop Bath", "Fixer", "Wash", etc.

For each step you configure: name, duration (minimum 30 seconds), chemical type (Chemistry / Rinse / Multi-Rinse), source container (C1, C2, C3, or WB), and whether to discard the chemical after use.

The three step types behave differently during execution: a Chemistry step fills once from a container and soaks for the whole step time (liquid recovered or discarded per the flag). A Rinse step fills once (from any source), soaks, and always discards to waste at the end. A Multi-Rinse step is not a single soak: the tank is repeatedly filled with fresh water (always from the water bath), agitated for one cycle — the "Multi-rinse cycle time" setting — then fully drained to waste, over and over until the step's total duration elapses. If the total time isn't an exact multiple of the cycle time, the last cycle runs longer so the step still ends exactly on time. This matches the Adeo dev.a behaviour and is ideal for final washes where the water must be changed frequently.

• Add: Tap "+" below the step list
• Edit: Tap a step to modify it
• Duplicate: Swipe left on a step
• Delete: Swipe left to reveal the delete button
• Reorder: Long-press and drag

Running a Process (Checkup)

Open a process and tap Play. The machine walks through pre-flight checks, then executes each step automatically.

Pre-flight checks: tank size selection, water bath fill, tank presence verification, motor check, and temperature stabilization (for temperature-controlled processes).

During execution: the screen shows the current step name and remaining time, chemical source, current/target temperature, and upcoming steps.

Stopping: "Stop now!" halts immediately (potentially unsafe). "Stop after!" waits for the current step to finish — the safer choice.

Splash Screen

The splash screen appears at boot and supports three modes, configured via Settings → Splash Screen:

Use Default — The built-in "Deep Ocean" splash: a hand-tuned composition with a teal-to-navy gradient, geometric shapes, and the "FILMACHINE" title in Montserrat 48. This is the factory default.

Random next boot — Each boot generates a completely new splash from scratch using a tick-derived seed. The PRNG (xorshift32) deterministically selects a palette, shape style, complexity, title position, and title font — producing a unique visual identity every time the machine starts.

Custom — Fine-tune the splash parameters manually: Palette (10 options), Shape Style (6 options), and Complexity (20–100 in steps of 20). The popup shows a live preview of the current configuration as the background behind its own controls, with a dark overlay for readability. Press the Random button to regenerate all parameters at once; if you like the result, it will be applied at next boot. The preview shows only the shape background (no title or play button) so you can evaluate the pattern clearly.

Title fonts — In Random and Custom modes, the title "FILMACHINE" is rendered with one of 9 fonts selected by the PRNG:

All fonts are converted from TTF/OTF to LVGL .c bitmap arrays using lv_font_conv with --no-compress --bpp 4 --range 0x20-0x7F (ASCII only, ~20–40KB each in flash).

Palettes — Cyberpunk, Aurora, Lava, Deep Ocean, Forest, Sunset, Machinery, Arctic, Neon, Pastel. Each defines a top/bottom gradient, 3 shape accent colors, and text/accent colors for the title.

Shape Styles — Overlapping Rects, Circles & Arcs, Mixed Shapes, Diagonal Bands, Grid Blocks, Radial Arcs.

The Settings Tab

The settings are grouped in sections, like the Tools tab; the whole page scrolls with its section titles. The app's Settings screen uses the same groups and the same wording.

The fill times are not settings any more: they are measured by the Maintenance fills in the Tools tab. The film loader's motor speed and cutter servo pulses (loadSpeed, cutterRestUs, cutterCutUs) are stored with the settings but are not shown on this page; they are set from the app's Load film screen (or in FilMachine.json).

All settings are saved automatically to the SD card when changed. Slider values are saved only when you release the slider (not during dragging) to reduce SD card wear.

The Tools Tab

• Clean machine — Automated cleaning cycle: select which containers to clean (C1, C2, C3), set the number of rinse cycles (1–5), and optionally drain the water bath when done. Only the selected containers are cleaned, in order: each cycle fills the container with water from the water bath and then pumps it back, with real-time progress shown via arc animations and remaining-time countdown. Stop pumps the water still in the current container back to the bath before ending. It can also be started, stopped and closed from the app (the popup shows the app's choices).
• Empty chemistry (machine v7) — One row: the popup asks which container (C1, C2 or C3) and moves its whole content into its recovery bottle through the RECOVERY outlet (valve A6, the seventh port of the collector). Four phases, all through the tank: bath water through the line to waste, the first 30 ml of the chemistry to waste (they carry away the water film), the chemistry into the bottle cycle after cycle (until its MIN sensor pulls air, or 1 litre), bath water through the line again. Nothing but that chemistry and a few tenths of a millilitre of water can reach the bottle. The popup shows source → tank → bottle bars with a drop running along the pipe, the four phases as dots, the remaining time; Stop drains the tank to where the liquid was going and ends the run. Also from the app (recover_start).
• Drain machine — Drains all containers (C1, C2, C3, WB) to waste sequentially. A confirmation screen lists the affected containers; once started, four colored tank bars animate from full to empty in real time, showing which container is currently draining, a ">> WASTE <<" indicator, and a countdown timer. The drain can be stopped at any time via the Stop button. It can also be started, stopped and closed from the app.
• Self-check — Guided hardware diagnostic wizard that tests all machine components in 8 phases: temperature sensors (5s), water pump (10s), heater (30s), valves (10s), the three containers C1/C2/C3 (10s each), and agitation motor (10s). The UI is split in two panels: a task list on the left showing icons per phase (check for done, dot for pending/skipped/stopped) and a detail panel on the right with phase description, real-time sensor data, countdown timer, and a progress bar. Three buttons control the flow: Stop (halts current phase), Start/Re-run (begins or repeats a phase), and Next (skips to the next phase). Each phase's state (done, skipped, stopped) is saved and visible when revisiting. When all phases complete successfully the title shows "Self-check complete!" in green; if any were skipped or stopped it shows "Self-check finished" in orange.
• Load film — Loads the film onto the reel with the built-in loader: choose 135 or 120 and press Start. The reel motor winds the film while the Hall sensor counts the turns; when the reel stops at the end of the film, the servo raises the blade and cuts, then half a turn pulls the tail inside and a beep says the tank is ready. Cut now cuts at once (e.g. when the 120 tape shows), Stop halts everything, and with the machine idle a Test blade button runs one blade cycle. The cut is refused if the reel stops too early (clip not hooked) or turns too long, and the motor is checked for rotation right after the start. The same cycle can be started from the app; a process cannot start while a film is loading.
• Import/Export — Backup and restore configuration to SD card (Export can also be run from the app; Import reboots the machine and stays on the display)
• Statistics — Completed processes, total time, cleaning cycles, stopped processes
• Software info — Firmware version (read from the running binary, also shown on the splash screen) and serial number
• Update from SD — Firmware OTA update from a .bin file on the SD card. The system reads the firmware version from the binary header, asks for confirmation, then writes it to the secondary OTA partition. After completion, a reboot applies the new firmware. If the update fails, the bootloader automatically rolls back to the previous version.
• Wi-Fi update — Starts a local web server on the board. A popup shows the board's IP address (e.g. http://192.168.1.42) and a randomly generated 8-digit PIN for security. The user opens the URL in any browser on the same network and sees a drag-and-drop upload page styled with the FilMachine branding. After uploading the .bin firmware file, it is streamed directly to the OTA partition. The board reboots automatically when complete. Wi-Fi credentials (SSID/password) are configured in the Settings tab.

Firmware Update (OTA)

The board supports two methods for over-the-air firmware updates. Both use the ESP-IDF dual-partition OTA mechanism: the new firmware is written to a secondary partition while the current one keeps running, and the bootloader swaps at reboot. If the new firmware fails to boot, automatic rollback restores the previous version.

Method 1: SD Card

1. Build the firmware: idf.py build
2. Copy build/FilMachine.bin to the SD card root, renamed as FilMachine_fw.bin
3. Insert the SD card into the machine
4. Go to Tools → "Update from SD" and press the play button
5. Confirm the version shown in the popup
6. Wait for the progress to reach 100%, then reboot

Method 2: Wi-Fi (Web Upload)

1. Configure Wi-Fi SSID and password in Settings
2. Go to Tools → "Wi-Fi update" and press the play button
3. The popup shows the board's local IP and a 8-digit PIN
4. On any device on the same network, open http://<board-ip> in a browser
5. You'll see a drag-and-drop page — drop the .bin file or click to select it
6. The firmware uploads in streaming and the board reboots automatically

Firmware File Format

The .bin file is produced by idf.py build at build/FilMachine.bin. It contains an ESP32 application image with an esp_app_desc_t header that stores the firmware version, build date, and SHA-256 hash for integrity verification.

Partition Table

The project uses a custom partition table (partitions.csv) optimized for the 16MB flash chip. Each OTA slot is 6MB, giving ~59% free space with the current firmware size (~2.5MB, measured on a clean build of v0.0.0.54 with the repository defaults).

# Name      Type  SubType   Offset      Size
nvs         data  nvs       0x9000      24KB     NVS key-value storage
otadata     data  ota       0xF000       8KB     OTA boot flag (which slot to boot)
phy_init    data  phy       0x11000      4KB     Wi-Fi PHY calibration data
ota_0       app   ota_0     0x20000      6MB     Firmware slot A (active)
ota_1       app   ota_1     0x620000     6MB     Firmware slot B (updated via OTA)
coredump    data  coredump  0xC20000    64KB     Crash snapshot (read into the SD boot log)
(free)      —     —         0xC30000    ~4MB     Unallocated

Note: after adding the coredump partition, regenerate the sdkconfig once (rm sdkconfig && idf.py build) so the CONFIG_ESP_COREDUMP_* defaults are picked up, then flash normally (idf.py flash also rewrites the partition table).

The bootloader alternates between ota_0 and ota_1: the new firmware is written to the inactive slot, and at reboot the bootloader swaps. If the new firmware crashes at startup, automatic rollback restores the previous working version.

Setting the Firmware Version

The single source of truth is version.txt in the project root, in the form MAJOR.MINOR.PATCH.BUILD (e.g. 0.0.0.54). ESP-IDF uses it as the application version, so the value shown on the splash and in Tools → Software version is read at runtime from the running binary via esp_app_get_description()->version; the simulator gets the same string from CMakeLists.txt, which injects it as FW_VERSION_STR.

./flash_p4.sh increments the BUILD field before every build. To do it by hand:

./scripts/bump_version.sh          # 0.0.0.54 -> 0.0.0.55
./scripts/bump_version.sh --show   # print the current version without changing it

For a real release, edit version.txt directly (e.g. 0.1.0.0).

Hardware Specifications

System Architecture

Target Board

Guition JC4880P433 (-DBOARD_JC4880P433) — the only supported hardware board.

Landscape Mode

The JC4880P433's physical display is 480×800 in portrait orientation. FilMachine uses it in landscape mode at 800×480. The display pipeline works as follows:

1. LVGL renders the UI into an 800×480 framebuffer
2. The PPA hardware engine rotates the buffer 90° to fill the 480×800 physical panel

Touch coordinates from the GT911 (which reports in 480×800 portrait) are inverse-mapped back to 800×480 LVGL coordinates. All of this is transparent to the UI code.

Expand IO Header (JP1) — JC4880P433 Pin Assignments

All external peripherals connect through the board's 2×13 Expand IO header (JP1):

All 12 P4 GPIO pins on JP1 are allocated — GPIO 28, the last spare, now drives the film loader's cutter servo.

Breakout Board (KiCad)

hardware/FilMachine_Breakout_v1/ holds a KiCad project (schematic, PCB, the Python script that generates them, an HTML preview) and a BOM for a 70×50 mm two-layer breakout board. It plugs onto the Expand IO header (called J9 in its files) and brings the signals out to 5.08 mm screw terminals — motor, OneWire temperature, flow meter, I2C, water level, Hall sensor and power — plus a 1×8 header for the remaining GPIOs, and it carries the 4.7 kΩ pull-ups for I2C and OneWire. As its BOM.txt warns, check the header's power-pin mapping against the actual board with a multimeter before the first power-on.

Peripheral Drivers

MCP23017 pin map (I2C 0x20):

Port A pins sit behind the #6318 MOSFET drivers (valves). Port B pins are raw push-pull GPIO on the board's bottom edge: B0–B5 are inputs (pull-up, LOW = water present), B6–B7 are heater outputs (HIGH = on).

Chemical Container Layout

Constraints

Bill of Materials (Components)

Everything the firmware currently expects, for costing a build or a custom board. Quantities are for the standard 3-chemistry layout; prices are intentionally omitted (they move — estimate locally).

Two spreadsheets in the repository root complement this list (both in Italian): DistintaComponenti.xlsx, a parts list with specs, quantities, prices and links, and FilMachine_Custom_PCB_BOM.xlsx, the design worksheet for a future custom PCB (BOM, JP1 pin map, MCP23017 map, power budget). The MCP23017 map in that worksheet belongs to the custom-board design; the mapping the firmware uses today is the one in Peripheral Drivers.

Controller & storage

Actuation & power drivers

Sensors

Power & misc

Future / diagnostics-ready (optional)

Film Reel Auto-Loader (3D-Printed Prototype)

Bench prototype v1 — files in 3D_Models/FilMachine_caricatore_v1/. The original notes, in Italian, are in that folder's README.

The loader winds the film onto the reel from the centre outwards, like the Rondinax: a motor turns the reel, a leader strip with a clip pulls the film out of the cassette, a guide arm bows it and lays it onto the ribs, and a cutter trims it when the winding is done. Formats: 135 and 120 on the same reel.

What it is and what it is not. It is an open test bench for validating the mechanics in daylight with scrap film. It is not yet light-tight or liquid-tight: that is the next phase, to be designed around mechanics that work.

Firmware status. This v1 bench (stepper + pendulum cutter) is not driven by the firmware. The firmware drives the loader built into the machine (v5): Tools → Load film (main/film_loader.c) winds with the agitation motor, counts the reel turns with the Hall sensor, and cuts with a servo on GPIO 28 — see The Tools Tab. The sequence in Planned firmware sequence is kept as the reference for the bench.

Contents

Each assembly contains 23 named, coloured bodies: the 19 parts used for that format plus the REF_ reference shapes (NEMA17 motor, servo, blade, 135 cassette or 120 spool). In Shapr3D every body can be hidden. All part faces are planes, cylinders and cones, so they can be edited directly.

How It Works

1. Adjustable reel (parts 01–04). Same principle as the OpenReel/Paterson reel, adapted to centre-out loading: a central tube with bayonet tracks, two flanges that slide on and lock with a 30° twist in two positions (35 mm and 120), and a central drum with the leader-strip anchor and the clip pocket. The flanges move symmetrically, so the film stays centred in both formats. Outer Ø 93.5 mm and tube bore Ø 26.3 mm, as measured on the OpenReel STEP files. The ribs have no outer lead-in and no ratchet: the film, under tension, rests with its edges on the back of the ribs (0.9 mm per side) and the emulsion touches nothing.
2. Guide arm (05 for 135, 06 for 120). It pivots on two screws. Its converging walls squeeze the edges and bow the film into an arc (6.5 mm deep on 135, 8.7 mm on 120): that way it passes between the rib tips and, as soon as it leaves the tip of the arm, it flattens out again and settles on the right turn. The sole rests on the previous turn, so the arm rises by itself as the reel fills. With the reel empty, a stop screw on the cheek plate holds it.
3. Turret (07–14). Two cheek plates, the bridge with the film slot and the blade slot, and the cradle for the 135 cassette or the one for the 120 roll (same four screws).
4. Pendulum cutter (10–12). A micro servo swings an arm that carries an ordinary 9 mm snap-off cutter blade: the tip crosses the slot from one side to the other and cuts the film against the ceiling of the bridge, like a sliding trimmer. It cuts the full width, 120 included.
5. Drive (15–19). NEMA17 on one upright, a single drive coupling for both formats (a spigot in the tube bore plus two teeth), a plug-type idler pin on the other upright, and the base.
6. Clip (20–21). A wedge jaw with a tooth, closed by a slider; it stays in the drum pocket.

Left: the adjustable reel, exploded (flanges, bayonet tube with the drum). Right: the pendulum cutter at three positions of its sweep.

Printing

PETG, 0.4 mm nozzle. No supports: every part is already oriented.

Fit clearance used everywhere: 0.15 mm (FIT in src/common.py). If your printer prints tight or loose, change that value and regenerate.

Parts to Source

• NEMA17 stepper motor (Ø5 × 24 mm shaft) + TMC2209 driver
• MG90S micro servo (or SG90) with the single-arm horn
• 9 mm snap-off cutter blade (0.4 mm), a piece at least 45 mm long
• M3 screws: 12 × M3×12 (bridge, cradle, servo mount), 9 × M3×10 (turret feet, upright feet, idler-pin retainer), 10 × M3×8 (motor, guide-arm pivot and stop, blade clamp), 1 × M3×6 grub screw + 1 M3 nut
• 1.75 mm filament: it serves as the leader-strip pin (drum and clip) and as the drum-to-tube dowel (2 pieces of 6 mm)
• Leader strip: a 16 × ~135 mm strip of scrap film or 0.15–0.2 mm PET (115 mm usable)

The holes marked "self-tapping" are Ø2.6: the M3 screw cuts its own thread in the PETG.

Assembly

1. Tube + drum: slide the drum to the middle of the tube and fix it with the two filament dowels.
2. Leader strip: one end around a piece of filament pushed into the hole of the drum, the other end in the head of the clip.
3. Flanges: slide them onto the tube with the teeth in the channels, push to the wanted position (35 or 120), then twist 30° up to the stop. Flange A goes on the motor side.
4. Turret: screw the bridge, the cradle and the servo mount between the two cheek plates, then fit the guide arm with its two pivot screws (they must leave it free to swing) and the stop screw.
5. Cutter: glue the servo horn into its seat in the blade arm, then mount the blade with the edge towards the cutting side and the tip 75 mm from the servo axis (19 mm beyond the head of the arm).
6. Uprights and base; drive coupling on the motor shaft, held by the grub screw.

Use

135 — Cassette in the cradle with the lips up, towards the bridge; leader trimmed square. Arm raised. Bring the clip to the cassette, passing under the arm and through the central passage of the bridge, clip it onto the film (1 cm sticking out is enough), lower the arm. Start: the motor winds, stops at the end of the film, the blade cuts, and the motor takes up the tail.

120 — Flanges in the 120 position, arm 06, cradle 14. Roll in the cradle; unroll the backing paper until the film appears, then clip onto the film. While the motor winds, guide the paper up and back (as on the Rondinax 60). When the adhesive tape arrives: stop, advance 20 mm, cut.

Planned Firmware Sequence (Starting Values)

Reel turns: 0.83 of leader strip, then 8.2 turns for a 36-exposure 135 (5.9 for 24 exposures) and 4.6 turns for a 120. Length wound after θ radians: L = 23·θ + 0.175·θ² mm.

1. Servo parked (−26.8° from vertical).
2. Wind at 15–20 rpm, clockwise as seen from the idler-pin side.
3. End of film on 135: motor stall (StallGuard) at low current, or a maximum number of turns.
4. Cut: servo from −26.8° to +26.5° and back.
5. Take up the tail: another 0.6 turns.

Motor current, stall threshold and servo pulse widths have to be tuned on the bench: they have not been measured.

Checks Done on the Model

See verifiche.txt for the full output.

• All 21 parts are valid, single solids; neither assembly has any pair of interfering bodies.
• Bayonet: free insertion along the channel, free rotation up to the stop, locked beyond the stop and against pull-out, in both positions.
• Guide arm: no interference with the reel at three winding radii, 0.2 mm clearance per side.
• Cutter: sweep free of interference in 7 positions; the tip passes the ceiling of the slot by 1.1 mm at the edges of the 120; when parked, the blade stays 0.9 mm from the 120 film zone and 12.8 mm from the 135 one.
• Reel capacity: 1.83 m of film.

To Be Validated on the Bench

These are not guaranteed by CAD alone.

1. Forming the arc and laying the film on the ribs: this is the heart of the system. Parameters to retouch if needed: RIB_H, TIP_CLEAR, WALL_TIP, H_EDGE.
2. Clip grip under tension. For the first trials a piece of adhesive tape works too.
3. Bayonet without a detent: while winding, friction keeps it against the stop; for agitation with reversals a positive lock will be needed (a key in the channel).
4. Cutting force: estimated, not measured. If the MG90S is not enough, the mount has to be adapted to a larger servo.
5. End of film: stall detection to be tuned on 135; on 120 it is manual in this version, like pulling out the backing paper.
6. Fit in the developing tank: the tube is 71 mm long even in the 35 mm configuration.

Modifying the Model

All dimensions are in src/common.py. After a change, run cd src && python3 build_all.py (needs pip install cadquery): it re-exports parts and assemblies and re-runs all the checks.

Diagnostics & Bring-up Page

A hidden factory/bring-up screen for validating hardware (especially a custom board).

How to open:

• Board: on the splash, hold 2 fingers still for 3 seconds. Touch after the splash appears — a capacitive GT911 calibrates out fingers already on the panel at power-on.
• Simulator: press the small DBG button (top-left of the splash) — the mouse can't do multi-touch.

Live monitor (grouped panels, refresh ~3×/s): bath/chem temperatures, water-bath level (min/max), 3× chemical level (min/max), Hall magnet, flow (L/min + pulses), MCP23017 / SD / Wi-Fi status, and a System panel with ESP32-P4 internal chip temperature, free PSRAM, last reset reason, and uptime. A Power rails panel shows 12V/5V/3.3V (n/a until dividers + HAS_RAIL_MONITOR are provided).

Output controls (to test the board): toggle each valve (C1/C2/C3/WB/Waste/Rec — the recovery outlet on A6), run pump FW/RV/Stop, motor FW/RV/Stop, toggle heaters H1/H2 and the bath circulator (Circ, A7), play an audio test tone. Close turns every output off and returns to the splash.

Build-time Switches

Compile-time flags (in main/include/FilMachine.h and the board header) that change behaviour without touching logic:

Configuration & Persistence

All data is stored on the SD card as a single JSON file, FilMachine.json (the old binary .cfg was replaced — JSON is human-readable, hand-editable and version-tolerant). Parsing/serialisation uses a small dependency-free parser (main/mini_json.c) that builds on both the board and the simulator (no cJSON). Writes are crash-safe (.tmp + atomic rename).

Schema:

{
  "settingsParams": {
    "tempUnit": 0, "waterInlet": 1,
    "filmRotationSpeedSetpoint": 50, "rotationIntervalSetpoint": 10, "randomSetpoint": 20,
    "isPersistentAlarm": 1, "isProcessAutostart": 0, "drainFillOverlapSetpoint": 100,
    "multiRinseTime": 60, "lineRinseEnabled": 0, "lineRinseTime": 10,
    "tankSize": 2, "pumpSpeed": 100,
    "chemCalibFillSecs": 0, "wbCalibFillSecs": 0, "chemistryVolume": 2,
    "tempCalibOffset": 0, "chemCalibOffset": 0,
    "splashRandom": 0, "splashPalette": 3, "splashShapeStyle": 0,
    "splashComplexity": 40, "splashSeed": 0, "splashDefault": 1,
    "wifiEnabled": 0, "wifiSSID": "", "wifiPassword": "",
    "brightness": 100, "volume": 60, "invertPump": 0,
    "language": 0, "screenOffMins": 10
  },
  "processes": [
    { "name": "C41 Color Std", "temp": 38, "tempTolerance": 0.3,
      "isTempControlled": 1, "isPreferred": 1, "filmType": 1,
      "timeMins": 23, "timeSecs": 15,
      "steps": [
        { "stepNameString": "Developer", "timeMins": 3, "timeSecs": 15,
          "type": 0, "source": 0, "discardAfterProc": 0 }
      ] }
  ],
  "machineStats": { "completed": 0, "totalMins": 0, "totalSecs": 0, "stopped": 0, "clean": 0 }
}

Notes on a few fields: tempCalibOffset/chemCalibOffset are in tenths of a degree (int16, clamped ±30 °C); chemCalibFillSecs/wbCalibFillSecs are the measured MIN→MAX fill times in seconds (0 = uncalibrated, capacity used as fallback); step type 0=Chemistry/1=Rinse/2=MultiRinse; step source 0=C1,1=C2,2=C3,3=WB. lineRinseEnabled (0/1) turns on a line rinse after each chemistry step: after draining a chemistry step, the shared pump line is flushed with clean water from the water bath, discarded to waste, for lineRinseTime seconds (5–60 s) before the next liquid is drawn — clearing chemistry residue from the common tubing to avoid cross-contamination. Opt-in (default off); uses extra water, so watch the bath level when the water inlet isn't connected.

Auto-save triggers: creating/editing/deleting a process, changing any setting, toggling preferred, duplicating processes or steps, and recording a fill calibration.

Export writes a backup copy (FilMachine_Backup.json); Import restores from it and reboots. Generate a fresh SD file with scripts/genFilMachineCFG.py --realistic --output sd/ (see COMMANDS.md).

In the simulator these files live in an sd/ subdirectory of the directory the simulator is launched from (e.g. sd/FilMachine.json); the folder is created on first run if missing.

Language / Localization

The UI is fully bilingual: English (default) and Italiano. The language is selected in Settings → Language via a roller; on confirmation the machine saves the config and reboots automatically to rebuild the UI in the new language (the on-device UI is built once at boot).

Implementation: all ~350 UI strings live in a runtime lookup table (main/lang.c + main/include/lang.h) resolved through tr(). The xxx_text macros in FilMachine.h are untouched at call sites — they now expand to tr(STR_xxx). The table is generated/maintained by scripts/gen_lang.py, which holds the Italian dictionary; translations use ASCII apostrophes (Velocita') because the LVGL fonts are converted with --range 0x20-0x7F. The setting is persisted as "language" (0=EN, 1=IT) in FilMachine.json, exposed over WebSocket (set_setting, applied at next boot), and included in genFilMachineCFG.py.

To add or fix translations, edit the IT dict in scripts/gen_lang.py and mirror the change in main/lang.c (or regenerate). Adding a third language means extending lang_pair_t and the languageList roller options.

SD Boot & Crash Log

Every boot the firmware creates /log/boot_NNNN.txt on the SD card (the 20 most recent files are kept, older ones are pruned automatically). The file starts with a header — firmware version, build date, reset reason — and then captures in background all ESP_LOGx and LV_LOG lines (RAM-buffered, flushed to the card every 2 s so the UI is never blocked).

If the previous run crashed (panic or watchdog), the header also contains a PREVIOUS RUN CRASHED block with the offending task and program counter, read back from the core dump that the ESP32 saves to the dedicated 64KB coredump flash partition at panic time. The full dump stays in flash and can be decoded with idf.py coredump-info. This is the "black box": if the machine reboots on its own while no serial console is attached, pull the SD card and read the latest boot_NNNN.txt.

Not captured by design: bootloader output, the very first lines before the SD is mounted, raw printf calls, and the last ≲2 s before a hard crash (covered by the core dump summary instead). Module: main/sd_log.c (firmware only; the simulator links weak no-op stubs).

Typical Workflows

C41 Color Negative (38°C)

A standard C41 process: Pre-wash with water (1:00), Developer from C1 (3:15), Bleach from C2 (6:30), Wash (3:00), Fixer from C3 (6:30), Final Wash (3:00). Temperature control is critical — the machine maintains 38°C ± 0.3°C throughout.

Black & White (20°C)

B&W processes are more flexible: Developer from C1 (8:00), Stop Bath from C2 (1:00), Fixer from C3 (5:00), Wash (5:00). Temperature control can be disabled for ambient-temperature development, or set to 20°C ± 0.5°C for consistency.

E6 Slide Film (38°C)

E6 requires precise timing and temperature: First Developer (6:00), Wash (2:00), Color Developer (6:00), Wash (2:00), Bleach (6:00), Fixer (4:00), Final Wash (4:00). All at 38°C with tight ±0.3°C tolerance.

Developer Quick Reference

Build Commands

# ── Simulator (macOS/Linux) ──────────────────────────────
mkdir -p build800 && cd build800
cmake ..                                   # Configure (first time only)
make -j$(sysctl -n hw.ncpu) filmachine_sim # Build simulator (parallel)
./filmachine_sim                           # Run simulator (800×480 window)

# ── Tests ────────────────────────────────────────────────
make -j$(sysctl -n hw.ncpu) filmachine_test  # Build tests (parallel)
./filmachine_test                            # Run all 19 test suites

# ── Firmware (ESP32-P4) ──────────────────────────────────
cd ~/Documents/GitHub/FilMachine_Reworked       # Must be in project root!
. $HOME/esp/esp-idf-v5.5/export.sh        # Load ESP-IDF environment
idf.py set-target esp32p4                  # First time: set RISC-V target
idf.py build                               # Build firmware
idf.py flash monitor                       # Flash + open serial monitor
idf.py flash                               # Flash only (no monitor)
idf.py monitor                             # Serial monitor only (Ctrl+] to exit)
idf.py size                                # Show firmware size breakdown

Rebuilding After Code Changes

# Simulator: just run make again (incremental, from build800/)
cd build800 && make -j$(sysctl -n hw.ncpu) filmachine_sim

# If you added new .c files to CMakeLists.txt, re-run cmake first:
cd build800 && cmake .. && make -j$(sysctl -n hw.ncpu) filmachine_sim

# Build + run tests in one shot:
cd build800 && cmake .. && make -j$(sysctl -n hw.ncpu) filmachine_test && ./filmachine_test

# Firmware: idf.py handles incremental builds automatically
idf.py build

# Flash immediately after build:
idf.py build && idf.py flash monitor

Clean Rebuild

# Simulator: wipe build directory and reconfigure
rm -rf build800 && mkdir build800 && cd build800 && cmake ..
make -j$(sysctl -n hw.ncpu) filmachine_sim

# Firmware: full clean (also needed if sdkconfig changes)
idf.py fullclean
idf.py build

Generating a Firmware Update File

idf.py build
# The .bin file is at: build/FilMachine.bin
# For SD card update, rename and copy:
cp build/FilMachine.bin /Volumes/SDCARD/FilMachine_fw.bin

Generating Sample Data

python3 scripts/genFilMachineCFG.py --realistic --output build800/sd/

Common Troubleshooting

# "CMakeLists.txt not found" when running idf.py
# → You're in the wrong directory. Run from the project root, not build800/

# Simulator won't compile after adding a new .c file
# → Re-run cmake: cd build800 && cmake ..

# LVGL not found
# → CMake clones it on the first configure. To do it by hand, from the project root:
#   git clone --depth 1 --branch v9.5.0 https://github.com/lvgl/lvgl.git

# Serial monitor garbled output
# → Check baud rate: idf.py monitor -b 115200

# ESP-IDF not found / idf.py command not found
# → Source the environment: . $HOME/esp/esp-idf-v5.5/export.sh

# CMake: 'The "path" field in the manifest file ".../components/espressif__esp_lcd_touch/idf_component.yml"
#         does not point to a directory'
# → dependencies.lock stores the absolute path of that local component on the machine that
#   generated it. After moving or renaming the project folder (or on another computer), edit the
#   "path:" under espressif/esp_lcd_touch in dependencies.lock to the new location. Deleting the
#   lock file makes the component manager regenerate it, but with newer versions of the unpinned
#   dependencies (mdns, esp_lcd_touch_gt911 and two transitive ones), which are untested here.

License

Private project. All rights reserved.

Authors

PeterB — Hardware design & firmware FrankP — Software development & testing