firmware/docs/notes/10-hardware.md

Hardware & MCU topology

MCUs (Klipper multi-MCU)

Klipper MCU	Serial	Role
mcu	(main board, see printer.base.cfg on device)	X/Y/Z steppers, bed heater PD2, bed thermistor PC3
eboard	/dev/ttyS5	Carriage extruder board — ONE stepper driver shared by whichever head is mounted (PB14/PB15/PB12)
eheaterboard	/dev/ttyS4	4 hotend heaters PC6..PC9, 4 thermistors PC0/PA4/PA5/PA7, 24V rail PA3
levelboard	/dev/ttyS7	The fixed inductive "cylinder" under the bed — all three [e_stop X/Y/Z] sit on levelboard:PD0 and drive the nozzle-offset calibration. The carriage eddy used for G28 Z and bed mesh is [probe] on eboard:PG0 — see 25-app-vs-klipper-ownership.md

The app pokes ttyS4/S5/S7 (sends a char, waits for "Ready") before starting Klipper. Other serial: /dev/ttyS3 = drying box (own protocol, not a Klipper MCU).

The bootloader handshake, as decompiled

Not reconstructed from behaviour — this is _Z17bootSerialHeatMcuv, _Z23bootSerialMainEboardMcuv and _Z23bootSerialLevelBoardMcuv disassembled out of usr/prog/PROGRAM/software/firmwareExe (1.9.7). The three are the same function with a different device path and different printf strings; usr/prog/klipper/checkEboard is a separate, older -O2 build of the eboard one.

open(dev, O_RDWR)                  # no O_NOCTTY, no O_NONBLOCK
fcntl(fd, F_SETFL, 0)
tcgetattr; cfmakeraw
c_cc[VMIN]=0; c_cc[VTIME]=1        # MIPS: VMIN=4, VTIME=5
cfsetispeed/cfsetospeed(B115200)   # 0x1002 on MIPS
c_iflag &= ~(IGNBRK|ICRNL|IXON)    # &= ~0x501
c_oflag &= ~OPOST
c_cflag  = (c_cflag & ~(CRTSCTS|PARODD|CSTOPB|CSIZE)) | CLOCAL|CREAD|CS8
c_lflag &= ~(ISIG|ICANON|ECHO|ECHOE)
tcsetattr(fd, 0x540E, &tio)        # see below

isReady = 0; isAck = 1
for (i = 0; i < 50; i++) {         # ~5s ceiling at VTIME=1
    n = read(fd, buf, 50)
    if (n == 0) continue
    if (find(buf, "Ready") != npos) { isReady = 1; break }
    else                           { isReady = 1 }      # ttyS5/ttyS7 only
}
send = 'A'
if (isReady)
    for (j = 0; j < 50; j++) {
        write(fd, &send, 1)
        read(fd, &recv, 1)
        if (recv == 6) { isAck = 1; break }
    }
close(fd)
return (isReady == 1 && isAck == 1) ? 0 : -1

Four things worth keeping in mind, all of which bit us:

• 'A' goes out fifty times, not once. The board gets fifty chances.
• A non-0x06 reply is ignored. isAck is initialised to 1 and is never assigned 0 anywhere in the function, so the ack byte cannot fail the handshake — it only decides whether the loop stops early. The level board answers 0x01 every time. Refusing the handshake over that byte is what stranded ttyS7.
• The ready phase differs by board. On ttyS4 only a literal "Ready" sets isReady. On ttyS5 and ttyS7 any byte does, banner or not — which is why checkEboard happily sends 'A' at an eboard that is already running Klipper and is just returning garbage at the wrong baud. ff_mcu_bringup.py deliberately does not copy that: only a banner earns a write. Since 2026-08-25 checkEboard is no longer called at all — ff_mcu_bringup.py covers ttyS5 too. Dropping it loses nothing: the binary is 9KB holding one function (_Z23bootSerialMainEboardMcuv), hard-wired to /dev/ttyS5, importing only the tty calls and printf. It flashes no firmware and opens no other device. It is still on the firmware partition; nothing runs it.
• tcsetattr(fd, 0x540E, ...) — that is TCSETS, where POSIX wants TCSANOW/TCSADRAIN/TCSAFLUSH. Both binaries do it, so it is in FlashForge's source, not a build artefact. It evidently does not fail on the printer (the routines go on to print their read loop), but ff_mcu_bringup.py passes TCSANOW, which is correct either way.

The ready phase is only ~5s and it does not wait for a second banner, so stock only ever worked when it ran immediately after the board powered up. The bootloader re-sends its banner on a period longer than that, which is why a bring-up run later in the boot can see nothing at all and still be looking at a board in its bootloader.

Extruder config (embedded default printer.cfg)

All four [extruderN] sections share the same step/dir/enable pins — only the mounted head is electrically active; the fork tolerates the duplicate pin claims (vanilla Klipper would refuse). Gear ratio 6.5:1, rotation_distance 19.15, Generic 3950 sensors, max_temp 350.

Klipper objects the UI expects (all present in the stock config)

• Heaters/sensors: extruder..extruder3, heater_bed, heater_generic chamber_heater (Pro only — it lives in printer.chamber.cfg, and the plain Creator 5 gets [temperature_sensor chamber] instead), temperature_sensor ptcTemp, temperature_sensor extruder_servo_value (eboard:PA0), temperature_sensor adc_current_value (eheaterboard:PC1). temperature_sensor motor_value (sensor_type: motor_current_sensor, eboard:PA1) is real and ships, but in printer.motor.cfg, not printer.base.cfg — so printer.base.cfg does not include it and the machine's own printer.cfg must. MOTOR_STOP, MOTOR_GRAB and the rest of the lock macros live in that same file, which is why ff-toolchange.cfg can name them.
• Fans: fan_generic fanM106 (part fan, via custom SET_FAN_M106), chamber_fan, chamber_cool_fan, chamber_heat_fan, chamber_loop_fan.
• Buttons (gcode_button): extruder_pos1..4 (head present in dock N), extruder_grab1..4 (head on carriage), frontDoor, topDoor. That is the whole family — confirmed against this printer's printer.base.cfg (see ff-toolchange.cfg's sensor note): there is no bare extruder_grab, no extruder_check_pos, no servo_min/servo_max, and motor_pin is commented out in printer.motor.cfg.
• Filament: filament_switch_sensor fd_ex0..3 (presence), custom motion sensors fm_ex0..3.
• Steppers: manual_stepper gear_stepper (the tool LOCK motor, not a feeder; its endstop doubles as the lock status signal — see 30-toolchange.md).
• Fork's virtual_sdcard extra status fields: channel, refuelling, after_channel_g1, doingChangeEx.