A workshop prototype can work on its creator's desk and still take too long to set up anywhere else. The next person may have a different computer, a different USB port number, or a project file without its matching firmware. For an education team or a kit maker, those gaps eat the time meant for the activity itself.
We went through this with our own block-programming setup: a Raspberry Pi Pico-based controller board with plug-in sensor and output modules on a mounting platform, programmed with BIPES, a browser-based block editor for MicroPython. The pieces of a good setup record already existed: board photos, firmware steps, browser connection screens, connector artwork and module close-ups. The work was making their relationship clear enough for someone else to follow.
Preserve the exact starting arrangement
Record these together:
- the controller and board revision;
- the editor address;
- the firmware filename;
- one reference project known to work.
Our setup used a firmware file named RPI_PICO-20240602-v1.23.0.uf2. That pairing records what worked for this board at that time. It is not a reason to flash every board with the same file.
Treat firmware loading and the normal serial connection as separate checkpoints. During firmware loading, the Pico appears as a USB drive named RPI-RP2. During normal use, the editor asks the browser for permission to connect to a serial device, which appeared as "Board CDC" with a port number that differs between computers. Someone who reached the first screen has not necessarily reached the second.
Check browser access before the day. A browser-based editor depends on Web Serial, which is not available in every browser. Test on the actual computers planned for the activity. Record the editor URL too, because older screenshots can show a different host.
Show where the program meets the cable
Our board guide separates connector names from GPIO numbers. The board artwork labels sockets such as I2C0, I2C1, UART0, AIN0, DIO0 and DIO1, while the program refers to GPIO numbers. A participant first finds a named socket, then selects the matching signal in the program. Putting both views on one setup sheet works better than assuming the socket name explains the code.
The module close-ups show another detail: a four-wire connector can include an unused position marked NC (not connected). On our vibration module the active signal is labeled DOUT; on the light-sensor module it is AIN. A cable that fits does not make those positions interchangeable, and choosing the other GPIO in the same connector can give no useful reading at all.
Use one simple, known project to check the setup before introducing a multi-module activity. Ask the next person to identify the board, connect it, load the intended file and describe the expected output. Note where the instructions fell short. Do not quietly fill in missing steps yourself and then call the setup independent.
Classroom platforms such as micro:bit's teaching tools separate sharing projects from setting up devices. Those facilities are not features of a custom block editor, so the practical starting point is a small, clearly labeled set of local project materials.
Package the activity around a reproducible result
Each activity package should include:
- a wiring photograph of the specific board revision;
- the block project file and any driver files it needs;
- the expected console message and the action that should produce it;
- how to stop a running program and return to the starting state.
A short assembly video helps with orientation and mounting. Ours covers peeling the protective film from the acrylic panels, fixing the controller with screws and standoffs, fitting the side panels and securing the top. Written labels still need to identify the exact files and connections, because a video cannot tell anyone which firmware is on the board.
Save a clean reference project before participants change it. That gives both the teacher and the learner something concrete to compare when a result changes.
What this does and does not show
This is a record of setup steps, not a measured improvement in classroom outcomes. The test that matters is whether someone other than the builder can reproduce the chosen exercise on the intended equipment, without help.
The same discipline carries over when a kit moves toward a small production run: a fixed board revision, a pinned firmware file, a reference project and a short functional check per unit. Writing it down for a workshop is a cheap rehearsal for writing it down for a batch.