Every pin, part and setting on the MakerBuddy board.

MakerBuddy is a learning board built around an ESP32, a small computer with Wi-Fi. The kit's board is the MakerBuddy IoT Kit V1.0. It comes in purple or green, and both colours are the same board.

This page matches firmware 2.10 and web app 3.6. It was checked on 28 October 2026. If this page and the printing on your board ever disagree, trust the board.

Every kit has the board with its ESP32 DevKit, 6 parts built into the board and 9 parts that plug in. Each socket is labelled, and most plugs fit only one way round. The distance sensor and the text screen use four wires that you match by name.

Each card shows the part's pin (GPIO), what the board reports, the signal it uses and the lesson that teaches it. Pick a card to ring the part on the picture. Each picture opens full size, so you can zoom in on a phone.

Pin notes

• Reading speed: the board reads every sensor once a second.
• Analog pins: pins 32–35 are on the ESP32's first analog converter (ADC1), so they keep working while Wi-Fi is on.
• Distance: the board keeps readings from 2 cm to about 4 m. It stops listening for the echo after 24 ms, which is about 4 m, so the firmware's own 500 cm limit is never reached. A missed reading keeps the last good distance.
• Soil calibration: "dry" and "wet" both stay within 0–4095. If you set them equal, moisture shows 0.
• Separate timers: the blue light and the three colours use PWM channels 0–3 on the first timer. Since firmware 2.8 the servo has its own channel (8, 16-bit) on the second timer. So changing the colour light never disturbs the servo, on any Arduino-ESP32 3.x core.
• Servo position: the servo keeps holding its last angle. It cannot report where it really is.

The kit photo at the top of this page also shows connector cables, a small bulb, a small fan, craft sticks and a screwdriver. Ask us to confirm what ships with your order.

You also need

• A computer, iPhone or iPad with a web browser. Choose your dashboard says which browsers work. Android phones cannot be used yet.
• A 2.4 GHz Wi-Fi network. A phone hotspot works too.
• A micro-USB cable and a 5 V USB power source for the board.

The board runs on 5 V from a USB cable plugged into the ESP32 DevKit's micro-USB port. The DevKit turns the 5 V into the 3.3 V its chip needs.

The board joins your own Wi-Fi, and the dashboards talk to it straight over that network. You set it up once per board and network. The step-by-step setup is in the documentation.

What your Wi-Fi needs

• 2.4 GHz. The board cannot use 5 GHz networks.
• Just a name and a password. A network with a sign-in web page (captive portal) or a username (enterprise Wi-Fi) will not work. A phone hotspot works.
• One network for everyone. The board and the learners' devices must be on the same network.

Not sure about your school Wi-Fi? Check it in four questions.

How the board uses the network

• Setup mode: a new board, or one whose Wi-Fi was reset, makes its own network called MakerBuddy_XXXX, with the password 12345678. The XXXX comes from its hardware (MAC) address. Its setup page is at http://192.168.4.1.
• Joining: up to 3 tries. Each try waits up to 10 seconds (20 checks, half a second apart).
• Finding it: by its IP address, or as name.local (mDNS) once it has a saved name.
• Traffic: plain HTTP and WebSocket on port 80. Firmware 2.10 has no HTTPS or secure WebSocket mode.

Firmware 2.10 is built for a trusted local classroom network. It has no login and no encryption. Read these limits before you connect it, then follow the four steps below.

What to do

1. 1

   Keep it off the internet

   Never make the board reachable from the internet. Don't open or forward port 80 to it.

2. 2

   Use a separate classroom network

   Where you can, put the boards on their own classroom Wi-Fi.

3. 3

   Keep real passwords off it

   Don't use passwords that protect anything important on the boards' network.

4. 4

   Not for safety decisions

   Don't use MakerBuddy readings or controls for medical, industrial, life-critical or certified safety decisions.

What uses the internet

• No accounts. Readings and commands go straight between the dashboard and the board on your own Wi-Fi.
• The internet is needed only to open the web app or to install an extension.
• The Chrome and Edge extension and the web app use Google Analytics. The Firefox and Safari extensions do not.

The newest firmware is 2.10. The dashboards can't install it over Wi-Fi yet. They only send the board update files from plain http:// links, and the 2.10 file on GitHub uses https://. So they show: "New version 2.10 available. This download requires manual installation through Arduino IDE."

To install 2.10, use a computer, a USB cable and the Arduino IDE. The steps are in Install by USB.

The dashboards look for updates in the firmware release feed (opens in a new tab), a firmware.json file on GitHub. They wait up to 15 seconds and don't follow redirects.

When a wireless update runs, the board:

1. 1

   Erases all saved settings

   The whole iot-kit store: Wi-Fi, board name, rules, calibration, and the screen and mapping settings. This happens before the download starts, so even a failed update wipes them.

2. 2

   Pauses its timers

   For the sensors, the screen and blinking. If the update fails, they stay paused until you restart the board.

3. 3

   Downloads the file

   Over plain HTTP, straight into the ESP32's updater. It does not check where the file comes from or whether it is genuine.

4. 4

   Shows progress

   On the screen, then restarts when the update is complete.

The rest of this page explains exactly how the firmware behaves: the servo, the screen, rules, timing and saved settings. You don't need it to teach the lessons. The lessons use the dashboard and rules, with no code.

The message formats (REST and WebSocket) are in the documentation, and so is building the firmware.

Only one thing controls the servo at a time, and the board decides which. Live readings report the current owner as so.

While another owner holds the servo, manual commands are refused. REST answers 409, and WebSocket replies with an e error. The board enforces this lock only for the servo. For the light, buzzer and relay, "locked" is a dashboard warning.

Following a sensor

• Which sensors: soil, gas, light or humidity (0–100), DHT11 temperature (0–50 °C) or DS18B20 temperature (−55 to 125 °C) can drive the servo across 0–180°. You can reverse the direction. The knob, motion, button and distance are not offered.
• No twitching: each new reading counts for 35% of the smoothed value. Changes under 3° are ignored. Each move takes 500 ms.
• Safe pause: if the DHT11 or DS18B20 fails, or a reading is older than 3.5 seconds, the servo pauses and holds its angle.
• One at a time: sensor-to-servo and knob-to-servo switch each other off. Knob-to-light or knob-to-colour can run alongside either.
• After a restart: the chosen sensor and direction are saved, but following starts switched off.

Servo steps in rules

• Where to: a step can go to an angle, or move by an amount from the current angle. The amount is worked out once, when the step starts.
• How fast: a move takes from 0 (instant) to 1 hour, then holds for up to 1 hour.
• Sweeps (firmware 2.7 and later): Range moves from a start angle to the target (movement + hold). Range + reverse goes there and back (2 × movement + hold).
• Limits: angles stop at 0° and 180° and never wrap round. This is a servo that turns to an angle, not a motor that spins.

When rules compete

• A higher-priority rule can interrupt a lower one. The interrupted move later carries on from where it stopped, with the time it had left. Rules of the same priority wait their turn.
• From firmware 2.9, an active servo rule keeps the servo for its whole life. Sensor and knob following pause (their settings are kept) and can't be switched on.
• Stopping, disabling or deleting the rule frees the servo. So does a one-time rule finishing. Following then resumes from the held angle over 500 ms.

The 16×2 screen (I²C) either cycles through sensor screens or shows your own two lines. Your lines can include live readings with ten wildcards, from {temp} to {button}. All ten are in the tool below.

• 16 characters per line. A wildcard counts as the length of the value it shows right now. {temp} showing 24.5 uses 4 characters, not 6.
• How values look: one decimal place for {temp}, {humidity}, {ds18b20} and {distance}. Whole numbers for {light}, {gas}, {soil} and {pot}. YES or NO for {motion} and {button}.
• A line can grow too long later. Temp: {temp} fits today, but a value can get wider. Distance, for example, shows 999.0 before its first reading.
• Who checks: every dashboard checks the length. So does the board, for WebSocket screen commands and rule steps. The REST /api/lcd endpoint saves text without checking.
• Inside rules: screen text is saved in 17-byte fields. Wildcards are stored as short codes, so the saved layout never changes.

The board stores and runs up to 10 rules, each with up to 10 steps. Rules are saved on the board. They survive power-off and run again at power-on, unless someone stopped them by hand. Pressing Stop never switches outputs off.

• What a step can do: turn the blue light on or off or dim it, set the colour light to one of 7 colours or off, turn the buzzer or relay on or off, move the servo, or show text on the screen.
• Waits: each step can wait from 0 to 1 hour (3,600,000 ms) before the next.
• Loop types: Condition (runs while a sensor test is true), Timer (runs, then waits a set time after it finishes), Forever, and No loop (runs once).
• Starting: Condition rules watch whenever they are enabled, unless someone stopped them by hand. Autostart decides whether the other types start at power-on. A new enabled rule that is not a Condition rule starts as soon as it is added.
• Priority: Condition first, then Timer, then Forever, then No loop. A running rule locks only the part its current step uses, and only against lower-priority rules. A timer waiting for its next run locks nothing.
• Conditions: a condition must stay true for 0.3 seconds before the rule starts. If it turns false mid-run, the rule finishes that run, so clean-up steps still happen.
• Timer gaps: the wait between timer runs counts from the end of each run. The dashboards allow up to 999 hours (stored as unsigned 32-bit milliseconds).
• Sensor tests: one sensor compared with a value, or two comparisons joined by AND or OR. A rule can add a second sensor test, joined by another AND or OR. "Equals" means within 0.1. Motion and button can only be tested as true (1) or false (0).
• Between class groups: delete the last group's rules in the dashboard. Holding the button does not clear rules.

New in firmware 2.10

• Start on a stopped Condition rule goes back to watching. Step 0 runs once the condition is true.
• The board re-sends the rule list to every connected dashboard within 1 second when a rule starts, finishes or stops on its own.

Fixed in 2.10 (older firmware still does this)

• Start marked a Condition rule as running at once. It could skip step 0, or run while the condition was false.
• A finished rule could keep its "Running" badge and its locks until the next rule command.
• Over WebSocket, the longest timer gaps became 0 ms. Over REST, they stopped near 596 hours.

The full REST and WebSocket rule formats are in the automation rules documentation.

Timers only raise a flag. The main program loop does the real work.

Wi-Fi setup and joining, buzzer beeps (500 ms), distance timeouts and updates can pause the loop for a moment. So the 20 ms servo step is the usual rate, not a guarantee.

All settings live in the ESP32's own storage, under the name iot-kit.

• After every restart, knob mapping is reset to none and sensor-to-servo following is off. Choose them again.
• What erases what: holding the button for 10 seconds erases only the Wi-Fi name and password (and resets the screen mode). A wireless update erases everything (see Updating the firmware).
• Saving rules: only the rules you changed are rewritten (using dirty and remove bitmasks). Running state resets when rules load, and leftover keys beyond the rule count are deleted.
• Changing the code: the structures in MakerBuddyTypes.h are saved as binary, so reordering or resizing fields needs a planned migration. That is why new rule options live in separate records (seqc_N, seqv_N). A rule without them behaves exactly as before.

The firmware is open source. You can change it and upload it from the Arduino IDE over USB.

• Licences: the firmware and web app are under GPL-3.0. The V1.0 board design (a Fritzing file) is under CC BY-SA 4.0.
• Where: all three are in the public repository MakerBuddy/MakerBuddy-V1 (opens in a new tab) on GitHub. The browser extensions and the phone app are not in it. No ready-made Gerber files or parts list are published.
• Toolchain: the Arduino IDE (or arduino-cli), board "ESP32 Dev Module" (esp32:esp32:esp32), "esp32 by Espressif Systems" 3.3.7 and 8 libraries. The firmware does not need ESP32Servo.
• Your own sketch replaces the MakerBuddy firmware. The dashboards and rules work again once you upload the MakerBuddy firmware again.

The library list, the PlatformIO notes and the upload steps are in Arduino development.