p5-wallplotter/lib/README.md

WallPlotter library

p5 helper for a Marlin polargraph over Web Serial. Coordinates are mm. Origin is machine home (G92). Y positive is up. Chrome or Edge, page on localhost or HTTPS.

Load from this package:

<script src="../../lib/WallPlotter.js"></script>

Example sketch: examples/zickzack/.

---

new WallPlotter(options?)

All options are optional.

Option	Default	What it is
baudRate	115200	Serial baud (must match Marlin)
stepSize	10	Keyboard jog step, mm
feedRateTravel	1500	Pen-up speed, mm/min (G-code F)
feedRateDraw	300	Pen-down speed, mm/min
penUpGcode	M280 P0 S90	Command to lift pen
penDownGcode	M280 P0 S50	Command to lower pen
penUpDelayMs	150	Pause after pen up, ms
penDownDelayMs	50	Pause after pen down, ms
machineXMin / machineXMax	-830 / 830	Overlay X extents, mm (idler spacing 1660)
machineYMin / machineYMax	-1200 / 800	Overlay Y; idlers at Y=800 (80 cm above work centre)
jogIntervalMs	150	Repeat delay while holding arrows, ms
maxLogLines	40	Serial lines in the selectable log (bottom-right)
previewMinDelayMs	30	Floor for preview segment wait, ms
previewFrameMs	16	Preview animation frame time, ms
timingMultiplier	1	Scale Test preview waits (2 = twice as slow)
onLog(line)	no-op	Extra callback for each log line
onStatusChange(status)	no-op	'connected' or 'disconnected'

---

Setup / UI

enableKeyInputs()

Keyboard controls. Call from setup(). No arguments.

Key	Action
C	Connect / disconnect
T	Run Test (preview)
H	Set home here (G92 X0 Y0) — required before Plot
0	Travel to (0, 0)
P	Toggle pen
← → ↑ ↓	Jog one step, pen up
Shift + arrows	Jog one step, pen down
+ / -	Jog step size 1–100 mm

enablePlotButtons(options?)

Adds Connect, Plot, and Test buttons. Expects global plot() and test() in the sketch.

Connect is shown only while disconnected (same as key C). While a path is running, Plot becomes Pause; while paused it becomes Resume. Test becomes Stop during a test.

Option	Default	What it is
parentId	'wallplotter-controls'	DOM id for the button row
connectLabel	'Connect'	Connect button text
plotLabel	'Plot'	Plot button text when idle
pauseLabel	'Pause'	Plot button while a path is running
resumeLabel	'Resume'	Plot button while paused
testLabel	'Test'	Test button text
stopLabel	'Stop'	Test button while a test is running

showInfos()

Draw HUD, path preview, bounds, and key help. Call every frame from draw(). Also runs held-arrow jogging when keys are enabled.

---

Speed

setSpeed(travel, draw)

Feed rates in mm/min. Used as G-code F and for Test preview timing. Clamped to 1–10000.

• travel (number): pen-up / move() speed. Or { travel, draw }.
• draw (number, optional): pen-down / draw() speed. Omit to leave draw rate unchanged.

Practical range about 100–10000. Values above 10000 are clamped. Do not use 0.

wp.setSpeed(6000, 2500);
wp.setSpeed({ travel: 6000, draw: 2500 });

setTimingMultiplier(mult)

Scales Test preview waits only. Plot is paced by Marlin (ok + M400).

• mult (number): 1 = match setSpeed estimate, 2 = twice as slow, 0.5 = twice as fast. Clamped to ≥ 0.1.

---

Path (buffered drawing)

move / draw / wait / speed only queue. Nothing is sent until runPath.

startPath()

Clear the path buffer. Returns this.

move(x, y)

Queue pen-up travel to (x, y) mm. Returns this.

draw(x, y)

Queue pen-down stroke to (x, y) mm. Returns this.

wait(ms)

Queue a pause. ms is milliseconds. On Plot, sends G4 P<ms>. Returns this.

speed(travel, drawRate)

Queue a mid-path speed change (mm/min, clamped 1–10000). Either argument may be omitted. Restored after runPath. Returns this.

runPath(testOnly) / runPath(commands, testOnly?)

Run the path. async.

• testOnly (boolean): true = preview only, no serial. false = send G-code. Home must be set for Plot.
• commands (array, optional): explicit list instead of the startPath() buffer.

Plot: wait for Marlin ok, then M400 (move finished). Test: animate using distance / setSpeed × timingMultiplier.

wp.startPath();
wp.move(-200, -200);
wp.draw(200, -200);
wp.wait(500);
await wp.runPath(false); // plot
await wp.runPath(true);  // test

Sketch: plot() → runPath(false), test() → runPath(true).

estimatePathMs(commands?)

Returns estimated duration in milliseconds for the current path buffer, or for commands if given. Uses setSpeed, queued speed(), wait(), and timingMultiplier. The HUD shows elapsed / est / remain while plotting.

stopPath() / stopPlot()

stopPath() aborts the current runPath after the in-flight command gets its ok (it does not cancel that wait — that was dropping the next ok).

stopPlot() first press is the same as Pause: finish the current stroke, then Resume continues. Second press stops the browser from sending more moves. The in-flight G1 still runs — this firmware does not have EMERGENCY_PARSER, so M410 cannot interrupt motion (and on a polargraph it desyncs belts). Unplug power for a hard stop.

pausePlot() / resumePlot()

Pause / first Stop wait for the current segment to finish (M400), then lift the pen. Do not resume after emergency stop until you re-home. Elapsed / remaining HUD time freezes while paused.

---

Serial / machine

All async. Coordinate moves on Plot require home (H) first.

connect()

Web Serial port picker, enable steppers (M17), pen up, query polargraph area (M665 → machine overlay bounds), M114. Reload/close releases the port (needed on macOS). If only one previously allowed port exists, it is reused.

disconnect()

Close the serial port.

send(line, options?)

Write one G-code line and wait for Marlin ok.

• line (string): command without newline, e.g. 'M114'.
• options.allowWithoutHome (boolean): allow G0/G1 before home. Default false.
• options.waitOk (boolean): wait for ok. Default true.
• options.timeoutMs (number): ok timeout. Default 15000. M400 / G4 use a longer timeout based on the move or dwell. After 1s with no ok, the log shows waiting for Marlin ok and the HUD says Waiting for plotter…. During a plot, a timeout pauses so Resume can continue; S / Stop does the same.

penUp(force?) / penDown(force?)

Send pen G-code and wait the pen delay. By default, no-op if already in that state. Pass true to always send (used by P and on connect) so you can test the configured angles.

moveTo(x, y)

Pen up, travel to (x, y) mm immediately (not queued). Requires home.

drawTo(x, y)

Pen down, draw to (x, y) mm immediately. Requires home.

goToZero()

moveTo(0, 0).

step(dx, dy, draw?)

Relative move in mm.

• dx, dy (number): delta mm
• draw (boolean, default false): true → drawTo, else moveTo

setHomeHere()

G92 X0 Y0. Sets local x,y to 0 and marks home as set.

---

Fields (read)

Field	Meaning
connected	Serial open
homeSet	Home was set with H / setHomeHere()
x, y	Current position, mm
isPenDown	Pen state
isPlotting	runPath in progress
isPaused	runPath is paused
feedRateTravel / feedRateDraw	Current speeds, mm/min
timingMultiplier	Preview wait scale
stepSize	Jog step, mm