Setup guide

Shelf Item Locator

Find anything on your shelves by name. Put items in boxes, record where each box is, and when you search the exact shelf and stretch of LED strip lights up so you can spot it across the room.

A garage with wooden shelves; one box is lit green after being searched for
Search an item on your phone and its box lights up on the shelf.
The idea

How it works

There are two parts. One coordinator (an ESP32) is the brain: it holds your whole item database and serves a web app. Any number of shelf nodes (an ESP8266 each) sit on your shelves and light up when told to. The nodes find the coordinator on your WiFi automatically, so there are no addresses to hunt down. You search in the web app, and it lights the right shelf.

Diagram: a phone and coordinator on the WiFi, with three shelf nodes reporting in
One coordinator, any number of nodes, all on your own WiFi.
Before you start

What you need

For each shelf node

  • A NodeMCU (ESP8266) board
  • WS2812B LED strips (2 to 4 strips per shelf, your choice)
  • A 330 to 470 ohm resistor for each data line
  • A 5V power supply sized for your strips
  • A 1000uF capacitor for each strip

For the coordinator

  • Any ESP32 dev board
  • No SD card needed, it stores everything on board

Software

  • The Arduino IDE
  • A USB lead for each board
This guide assumes you already have the ESP8266 and ESP32 boards installed in the Arduino IDE (through Boards Manager). If not, add them first, then come back here.
Step 0

Install the libraries

In the Arduino IDE open Sketch > Include Library > Manage Libraries and install these two:

LibraryUsed byWhat it is for
FastLEDNodesDrives the WS2812B strips
WiFiManager by tzapuNodes and coordinatorThe first boot WiFi setup portal

The coordinator only needs WiFiManager. Everything else it uses comes with the ESP32 core, so there is nothing else to add.

Tip. When you pick WiFiManager, make sure it is the one by tzapu, as there are similarly named libraries.
Step 1

Open the sketches

Unzip the download. Inside the firmware folder you will find two sketches, each in its own folder:

Double click a .ino file to open it in the Arduino IDE. Keep each sketch in its own folder, the IDE needs that.

Step 2

Flashing basics (the same every time)

You will flash the coordinator once and each node once. The routine is always the same:

1

Plug the board in

Connect the ESP board to your computer with a USB lead. Use a proper data lead, not a charge only one.

2

Pick the board

In Tools > Board choose your board: an ESP32 Dev Module for the coordinator, or a NodeMCU 1.0 (ESP-12E) for a node.

3

Pick the port

In Tools > Port choose the port that appeared when you plugged the board in.

No port showing? Your board needs its USB driver. Most boards use a CP2102 or CH340 USB chip. Install that driver, unplug and replug, and the port will appear.
4

Upload

Press the Upload arrow (top left). Wait for Done uploading. If a board will not take the upload, hold its BOOT button while it starts, then release.

Step 3

Set up the coordinator (the brain)

Do this one first, so the nodes have something to report in to.

1

Flash it

Open shelf_coordinator.ino, pick your ESP32 board and port, and Upload (Step 2 above).

2

Join its setup hotspot

On first boot it makes its own WiFi network called Shelf-Hub Setup. On your phone or laptop, join it. The password is configme123.

3

Point it at your WiFi

A setup page opens. Pick your home WiFi and enter its password. The coordinator saves it, restarts, and joins your network.

4

Open the app

On any device on the same WiFi, go to http://shelfhub.local/. That is your control panel. Leave it powered and you are ready to add nodes.

Tip. If shelfhub.local does not resolve on your network, find the coordinator's IP address from your router and use that instead.
Step 4

Wire a shelf node

Each shelf node drives its own LED strips, one data pin per strip. Choose how many strips a node has (2, 3 or 4) with a single line near the top of shelf_node.ino:

#define STRIP_COUNT   2   // 2, 3 or 4

The data pins are fixed: strip 1 to D2 (GPIO4), strip 2 to D1 (GPIO5), strip 3 to D5 (GPIO14), strip 4 to D6 (GPIO12). Wire only as many strips as your STRIP_COUNT. Two strips still behave as the classic top and bottom.

2 strips (top and bottom)

Wiring diagram: NodeMCU driving 2 WS2812B strips
2 strips, data on D2 (GPIO4) and D1 (GPIO5).

3 strips

Wiring diagram: NodeMCU driving 3 WS2812B strips
3 strips, data on D2, D1 and D5 (GPIO14).

4 strips

Wiring diagram: NodeMCU driving 4 WS2812B strips
4 strips, data on D2, D1, D5 and D6 (GPIO12).
Power the strips from the PSU, not the ESP. Join all grounds together (common ground). Put a 330 to 470 ohm resistor in series on each data line, and a 1000uF capacitor across each strip's 5V and GND near where the strip starts.
Step 5

Set up each node (zone)

Repeat this for every shelf.

1

Flash the node

Open shelf_node.ino, pick your NodeMCU (ESP8266) board and port, and Upload.

2

Join its setup hotspot

On first boot the node makes a WiFi network called Shelf-Node. Join it (password configme123) and pick your home WiFi, the same as you did for the coordinator.

3

Coordinator address (optional)

The setup page has a Coordinator address field. Leave it blank and the node finds the coordinator on its own. Only fill it in (with the coordinator's IP) if you want to pin it.

4

Name and order it in the app

Back in http://shelfhub.local/, open the Devices tab. The node now appears. Press Identify to flash that shelf so you know which one it is, then give it a name and drag it into the order you want. That is a zone.

Add as many nodes as you like. Each one shows up in Devices as it reports in.
Step 6

Using it

Add stock

In the app, open Add stock. Pick a zone, choose the strip and the stretch of LEDs the box covers, then open the box and add items with quantities. Finish the box when you are done.

Packing a lot at once? Open http://shelfhub.local/pack on your phone. Quick Pack grabs the next stretch of LEDs for each new box automatically and lights it, and you read the contents in by voice (Android Chrome) instead of typing. Type or paste (one item per line) works too.

Find something

Open Find and start typing. Tap a result and its shelf lights up at the exact spot. Then choose:

A phone running the Find app, with a box lit green on the shelf behind
Live search, tap a result, the box lights up on its shelf.
Keep it safe

Backup and restore

Your whole database is a single file on the coordinator. From Settings you can download a backup, and upload one to restore. If you prefer the command line:

curl http://shelfhub.local/api/export -o backup.db

That is the lot. For the full list of endpoints, so you can script it or wire in your own node, see docs/API.md in the download.