Set up your kit, then build on it.

For owners, teachers, parents and students. Everything here is done in a web browser, with no code. No kit yet? See how to get one.

Have these things ready. Tick each one off as you go.

Guest networks often stop devices on them from talking to each other. IT staff call this "client isolation". Ask them to turn it off for the board, or use another network.

Match each part to its photo before you plug it in. Each one goes into the socket with the same name printed on the board.

Boards come in purple or green. Both colours are the same MakerBuddy IoT Kit V1.0 design.

Good to know about some parts

• Distance sensor (HC-SR04): measures from about 2 cm to 4 m.
• Smoke and gas sensor (MQ-2): for learning only. Never use it as a real gas or smoke alarm.
• Soil moisture sensor: a coated blade (a "capacitive" sensor) with no metal prongs. No current goes through the soil. Wetter soil gives a lower raw number.
• Small motor (SG90 servo): turns to an angle from 0 to 180°. It does not spin round and round.
• Buzzer: on or off, with one tone. It cannot play different notes.
• Text screen (LCD): 2 lines of 16 characters.

For pin numbers and wiring diagrams, see where each part plugs in.

Do this once for each board, and again if the board moves to a new Wi-Fi network. Pick your device first, then follow the six steps. Your ticks are saved in this browser.

Board names

The board saves its name in small letters and numbers, up to 32 characters. Spaces and other symbols become a dash. This lets other devices find it as the name followed by .local.

Start Wi-Fi setup again

1. 1

   Hold the button

   Hold the board's push button for 10 seconds. You can do this in the first 3 seconds after switching on, or at any time while the board runs.

2. 2

   Watch the screen

   It counts down "WiFi Reset: 10 seconds", then shows "WiFi Reset!" and "Restarting...".

3. 3

   Set it up again

   The board restarts in setup mode. Go back to step 2 of the setup.

The reset clears only the saved Wi-Fi name and password, and sets the screen back to its normal display. The board's name, its rules and its soil settings stay saved.

If the board cannot join your Wi-Fi

The board tries 3 times, about 10 seconds each. Then its screen shows "Not Connected to" and the network name, and it turns its Wi-Fi off. It does not go back to setup mode by itself. Check the network against the Wi-Fi rules, then hold the button for 10 seconds and set it up again.

A dashboard is the screen where you see readings and control the board. Pick the one that matches your device. They all control the board the same way.

The first time you connect, the Chrome and Firefox add-ons ask your permission to reach your board. The phone app will ask for permission to use the local network.

Things to know

• In Chrome, Edge or Firefox, the web app shows a screen asking you to install the free MakerBuddy add-on for that browser. You cannot close that screen. So on those browsers, use the add-on.
• Safari on a Mac, iPhone or iPad opens the web app directly.
• Android phones: Chrome and Firefox show the same add-on screen, and phones cannot install these add-ons. Until the phone app is out, use a computer, an iPhone or an iPad.
• The web app address starts with http://, not https://. That is on purpose: the board only speaks plain http, and browsers do not let an https page talk to it. Your browser may show "Not secure" next to the address.
• You need internet only to open the web app or install an add-on. After that, readings and commands travel on your own Wi-Fi. There are no accounts.
• Readings on the dashboard update about every 2 seconds. The board reads its sensors every second.
• The board has no clock and keeps no history of readings. The dashboard shows live values only.
• Which cards you see, and their colours, are saved in your browser or app, not on the board. The phone app can show or hide cards but cannot change their colours yet.

What every dashboard can do

• Show the same 10 live readings.
• Control 6 outputs: the blue light, the colour light, the buzzer, the relay, the motor and the screen.
• Make the motor follow the knob or a sensor.
• Teach the soil sensor what dry and wet look like.
• Check for new board software.
• Build rules: create, edit, copy, reorder steps, start, stop, switch on or off, and delete.

You set all three in the dashboard. Programmers can find the command fields in Mapping commands.

Teach the soil sensor dry and wet

1. 1

   Dry

   Open soil calibration in the dashboard and press Start under Dry. Hold the sensor in dry air or dry soil. The box shows the live raw number. Press Save.

2. 2

   Wet

   Press Start under Wet. Hold the sensor in water or wet soil. Press Save.

Until you do this, the board uses 3000 for dry and 1200 for wet. Saved numbers must be between 0 and 4095. If dry and wet are the same number, moisture always reads 0.

Let the knob control a part

The knob can control the blue light's brightness, the colour light (turning through the colours), the motor's angle, or nothing. Each time the board restarts, the knob goes back to controlling nothing. This is on purpose, so choose again after a restart. If a running rule is using the same part, you cannot pick that part until the rule lets go of it.

Make the motor follow a sensor

Pick one sensor: DHT11 temperature (0–50 °C), DS18B20 temperature (−55 to 125 °C), or humidity, light, gas or soil moisture (each 0–100). The motor then turns across 0–180° as the reading changes. You can reverse the direction. It ignores changes smaller than 3° and moves smoothly instead of jumping.

The knob and a sensor cannot both drive the motor. Turning one on turns the other off. Your choice is saved, but it starts switched off after every restart. It also pauses while a rule with a motor step is running.

The dashboards check for new board software (firmware) by themselves. When there is a newer version, they show a notice with the release notes. Closing the notice hides it for 24 hours. Versions are compared number by number, so 2.10 is newer than 2.9.

Why version 2.10 needs a USB cable

A dashboard can install an update over Wi-Fi only when the file's link starts with plain http://. The 2.10 file is on GitHub, behind an https:// link. So every dashboard shows this message:

"New version 2.10 available. This download requires manual installation through Arduino IDE."

This means you install it from a computer, with a USB cable, using the free Arduino IDE program.

Install by USB

1. 1

   Get the Arduino IDE

   Install the free Arduino IDE on a computer.

2. 2

   Add ESP32 support

   In File > Preferences, paste the board address shown below into "Additional Board Manager URLs". Then open Tools > Board > Boards Manager, search for "ESP32" and install "esp32 by Espressif Systems" (version 3.x).

3. 3

   Add the libraries

   In Sketch > Include Library > Manage Libraries, install the 8 libraries listed in Arduino development.

4. 4

   Get the code

   Download the public source (opens in a new tab) and open Arduino Code/MakerBuddy/MakerBuddy.ino.

5. 5

   Pick the board

   Connect the board to the computer by USB. Choose Tools > Board > ESP32 Dev Module, then the board's port under Tools > Port. Set Tools > Upload Speed to 115200.

6. 6

   Upload

   Click Upload and wait until it finishes.

7. 7

   Check

   Open the Serial Monitor at 115200 baud. It shows the board's IP address once the board joins Wi-Fi.

The board address for step 2:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Find what you see, then try the fix.

You don't need this part to use the kit. It is for students and developers who want their own code to read the sensors and control the outputs. The free lessons do not teach this part: they use the dashboard and rules, with no code.

How the firmware behaves inside (servo, screen, rule timing, saved settings) is in Technical details.

This reference matches the current source: firmware 2.10, web app 3.6, the Chrome, Firefox and Safari extensions 2.15, and the phone app 1.10.2 (in source, not yet downloadable). Firmware 2.10 needs a USB install (why). Where 2.10 behaves differently from older firmware, this page says so.

The board itself keeps your settings and runs your rules. The web app, the add-ons and the phone app are remote controls on the same local network.

{DEVICE_HOST} is the board's IP address (for example 192.168.1.100) or its name followed by .local (for example makerbuddy-01.local).

REST is handy for checking the board and for linking it to your own code. The dashboards normally use WebSocket instead. POST endpoints read form fields, not JSON bodies. Where an endpoint takes state, send the text true or false.

The relay switches at once. Older clients may send onDelay/offDelay or the short od/fd fields; the firmware ignores them.

There is no /api/rules endpoint. Unknown routes (other than OPTIONS) return a JSON 404. CORS currently allows every origin and private-network access.

Sensor snapshot

GET /api/sensors returns short keys. It has no m field.

{
  "te": 25.5, "hu": 65, "d8": 24.8, "li": 75, "po": 50, "ga": 15,
  "sm": 45, "sr": 2034, "di": 123.5, "md": false, "bp": false,
  "ls": true, "lp": 200, "lb": false, "r": [255, 0, 128], "rs": false, "sp": 90, "lm": 0,
  "fh": 234567, "pm": 0, "pv": 0, "sc": 1, "so": 0, "si": -1, "ss": 0, "tg": 90,
  "sv": { "en": 0, "sn": 5, "il": 0, "ih": 100, "al": 0, "ah": 180, "iv": 0, "db": 3, "sm": 35 }
}

Sensor readings

• te: DHT11 temperature, °C
• hu: DHT11 relative humidity
• d8: DS18B20 temperature, °C
• li: Light level, 0–100
• po: Knob (potentiometer), 0–100
• ga: MQ-2 gas value, 0–100
• sm: Calibrated soil moisture, 0–100
• sr: Raw soil reading, 0–4095
• di: Distance in centimetres
• md: Motion detected
• bp: Button pressed

Output states

• ls: Blue light on or off
• lp: Blue light brightness, 0–255
• lb: Blue light blinking
• r: Colour light as [r,g,b]
• rs: Relay on or off
• sp: Motor angle
• lm: Screen mode: 0 normal, 1 custom

Board, knob and motor status

• fh: Free memory (heap), bytes
• pm: Knob link: 0 none, 1 blue light, 2 colour light, 3 motor
• pv: The knob's current output value
• sc: 1 when Range sweeps are supported (firmware 2.7+)
• so: Who controls the motor: 0 manual, 1 knob, 2 sensor link, 3 rule
• si: Index of the rule that holds the motor, or -1
• ss: Sensor link: 0 off, 1 active, 2 invalid or stale reading, 3 paused by a rule
• tg: Motor target during a move, otherwise the held angle
• sv: Sensor-to-motor link settings (see Mapping commands)

MQ-2 and soil values are for learning, not certified safety readings. A DHT11 or DS18B20 read failure shows as 0.0. The board accepts distance readings from 2 to 500 cm; in practice the sensor reaches about 4 m. Outside that window it keeps the last good value. Until the first good reading, distance shows 999.

Device and firmware snapshots

{
  "dn": "makerbuddy-01",
  "fv": "2.10",
  "ip": "192.168.1.100",
  "mc": "AA:BB:CC:DD:EE:FF",
  "up": 3600,
  "fh": 234567,
  "sd": 3000,
  "sw": 1200
}

dn is the board name, or empty when no name is saved. up is seconds since the board started. sd and sw are the saved dry and wet soil readings. GET /api/firmware returns fv (the version), oi (an update is in progress) and op (its progress).

Custom screen text

Custom screen lines can show live values with wildcards such as {temp}, for example text1=Temp%3A%20%7Btemp%7D (URL-encoded Temp: {temp}). Each finished line must fit 16 columns, and REST /api/lcd does not check that. The full wildcard list, how wide each value is, and a tool to try lines are in The LCD screen.

Connect to ws://{DEVICE_HOST}/ws. This is what the dashboards use. Frames must be final, unfragmented text messages of 4096 bytes or less.

When you connect, the board sends its identity (i), firmware status (f), the full rule list (q) and motor status (j). i is the same object as GET /api/device, and f the same as GET /api/firmware, each with an added "m".

Telemetry (s) goes to every client at most every 2 seconds. A new connection or a mapping change sends it straight away, unless one went out less than 2 seconds before. It has the same keys as GET /api/sensors (see the key lists), plus "m": "s".

Messages from the board

Commands you can send

Rules run on the board itself, even when no dashboard is open. A board holds up to 10 rules, each with up to 10 steps. A rule name can be 20 characters long. Each step does one action, then waits before the next step: 1 second unless you change it, from 0 up to 1 hour (0–3,600,000 ms). The loop mode (lm) decides when a rule runs:

Conditions can use bigger than (>), smaller than (<), at least (>=), at most (<=) and equal (==, which matches when the values are less than 0.1 apart). One sensor can use one comparison, or a range of two joined by AND/OR. A rule can add a second sensor expression and join the two with AND/OR, for example (distance < 20) AND (soilMoisture < 20). The dashboards offer motion and button only as true (1) or false (0).

relay_on and relay_off are for low-voltage things only, never mains electricity. A misspelled sensor name is treated as temperature, so check the spelling. In a rule, buzzer_on keeps the buzzer on until a buzzer_off step.

Build a rule

Pick the parts of a rule below. The tool writes the matching X message and says in plain words what the rule will do. It sends nothing to a board.

Example: plant alert

{
  "m": "X",
  "a": 0,
  "s": {
    "e": 1,
    "n": "Plant alert",
    "lm": "condition",
    "as": 1,
    "lr": "soilMoisture",
    "lo": "<",
    "lt": 25,
    "rg": 0,
    "c2": 1,
    "lr2": "temperature",
    "lo2": ">",
    "lt2": 30,
    "rg2": 0,
    "co": "AND",
    "st": [
      { "a": "led_on", "v": 255, "d": 0 },
      { "a": "buzzer_on", "v": 0, "d": 500 },
      { "a": "buzzer_off", "v": 0, "d": 1000 },
      { "a": "led_off", "v": 0, "d": 1000 }
    ]
  }
}

Rule fields

• e: Enabled (1) or not (0)
• n: Name, up to 20 characters
• lm: Loop mode: condition, timer, forever or none
• as: Autostart: start at power-on (modes other than condition)
• tt, ld: Timer type (interval) and interval in ms
• lr, lo, lt: First sensor, its comparison and its number
• rg, ro, o2, t2: Range on the first sensor: on (1), AND/OR, second comparison and number
• c2: 1 turns on the second sensor expression
• lr2, lo2, lt2: Second sensor, its comparison and its number
• rg2, ro2, o3, t3: Range on the second sensor: on (1), AND/OR, second comparison and number
• co: Joins the two expressions: AND or OR
• st: Steps: each has a (action), v (value) and d (wait in ms); lcd_display also has lm, t1 and t2
• i, ms, rn: Only in the q list: index, manually stopped, running

Managing rules

X.a is 0 add, 1 delete, 2 start, 3 stop or 4 toggle enabled. All but add also need the rule index i. There is no update action: when you edit a rule, the dashboard deletes it and adds the new version, which can change the order.

How rules start, lock parts and compete, and what changed in firmware 2.10, is in How rules run.

In a servo_move step, v is the angle to move to. Optional fields set how the motor gets there:

{ "a": "servo_move", "v": 150, "d": 1000, "rv": 0, "mv": 2000, "sw": 2, "sa": 30 }

This step moves from 30° to 150° over 2 seconds, back over 2 seconds, then holds for 1 second. REST rule forms use stepN_relative, stepN_movementMs, stepN_sweep and stepN_startAngle. Limits, and what happens when rules compete for the servo, are in Servo control.

These are the commands behind the knob and motor settings in Part 1.

Sensor-to-motor link (J or /api/servomapping)

sn picks the sensor: 0 DHT11 temperature (0–50 °C), 1 humidity, 2 DS18B20 temperature (−55 to 125 °C), 3 light, 4 gas or 5 soil moisture (each 0–100).

Each command replaces the settings. A missing en turns the link off. A missing iv means not reversed. A missing sn keeps the current sensor. Missing il/ih/al/ah use the sensor's full range and 0–180°, with a 3° deadband (db) and 35% smoothing (sm).

/api/servomapping returns 400 for invalid values and 409 when you turn it on while a rule holds the motor.

Knob link (P or /api/potmapping)

0/none, 1/led, 2/rgb or 3/servo. servo returns 409 while a rule holds the motor.

The firmware is Arduino Code/MakerBuddy/MakerBuddy.ino in the public source (opens in a new tab). For step-by-step upload, see Install by USB.

• Board: ESP32 Dev Module (esp32:esp32:esp32), with "esp32 by Espressif Systems". Firmware 2.10 is built and checked with core 3.3.7.
• Serial Monitor: 115200 baud.
• Size: firmware 2.10 fills about 97% of the program space (1,284,130 bytes), so there is little room for extra code.

Libraries

• ESPAsyncWebServer and AsyncTCP: the web and WebSocket server.
• ArduinoJson: REST and WebSocket messages. The code uses the 6.x API and compiles with 7.4.2, the checked version.
• DHT sensor library and Adafruit Unified Sensor: read the DHT11.
• OneWire and DallasTemperature: read the DS18B20 probe.
• LiquidCrystal_I2C: drives the 16×2 screen.

You do not need ESP32Servo. The firmware drives the motor itself, on LEDC channel 8 at 50 Hz.

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
  me-no-dev/ESPAsyncWebServer
  me-no-dev/AsyncTCP
  bblanchon/ArduinoJson@^6.21.3
  paulstoffregen/OneWire
  milesburton/DallasTemperature
  adafruit/DHT sensor library
  adafruit/Adafruit Unified Sensor
  marcoschwartz/LiquidCrystal_I2C

The board also has spare UART and I²C sockets. Using them needs your own code.

Uploading your own sketch replaces the MakerBuddy firmware until you upload it again. Before you upload, check the board and the serial port, keep a copy of a firmware file you know works, and write down the settings that matter. Test on the real board.