Laberty devices: build a button box, knob or sign for your printer

A Laberty device is a small controller that sits next to the printer. It can be a touchscreen, a round knob, an e-ink sign, or a box with buttons, switches and lights. For example:

• one big button that prints every label that is waiting, with a light that blinks while any are
• a 3-way switch that tells Laberty which roll is loaded
• a knob you turn to pick a waiting label and press to print it

The Device Builder (Admin → Devices) lets you design one, try it on screen, and then gives you the wiring and the firmware.

Devices come with the print bridge, so they need a paid plan and a running print bridge.

Controls built into a board, like the knob on an Elecrow rotary display or an onboard light, don't count toward inputs and outputs.

Start a device

Open Admin → Devices and choose one of four ways to start:

1. Pick a kit or preset. Ready-made starting points, such as "Grandma's print button box", "Printer status sign", "Touchscreen by the printer" and "Roll selector + status LEDs".
2. Answer questions. Pick no display, round, rectangle or square, then touch or not, e-ink or not, and the size. Laberty shows the boards that match. If you're not sure, press Not sure: suggest 3.
3. Paste a product link. Laberty works out which board it is, often without even opening the page. Some shops, Amazon especially, block this; paste the product's title instead.
4. Describe it to the assistant. Say what the device should do in plain words, and the assistant drafts it. This uses AI actions from your plan.

Your draft is saved as you go, so you can close the page and come back to it later.

Controls

Add the parts your device has: buttons, toggle and rocker switches, 3-way or rotary selectors, rotary encoders, LEDs, RGB LEDs, analog and 4-20 mA sensors, relays and buzzers.

• Pins. The pin list only offers pins that are free and safe on your board. A pin with a note (like a boot pin) shows the note under it.
• What it does. Each part has a row per gesture: press, long press, double press, switch on and off, each position of a selector, turning a knob, or a reading going above or below a level.
  • Disruptive commands only work on a long press, so a bump can't do them: skipping labels, cancelling everything queued, pausing the print bridge, "not sure which roll is loaded", the relay and webhooks. A switch or a selector position counts too, where it makes sense. Reprinting isn't one: pressing twice within 10 seconds prints once.
  • Commands marked Business are locked on Home.
• What it shows. Lights, relays and buzzers follow what's happening, such as labels waiting, a printer problem, the bridge offline, or the roll being confirmed. Pick a pattern for each (on, slow blink, fast blink, pulse) and, for an RGB LED, a colour.

The bar at the bottom shows how many inputs and outputs you've used on your plan, and whether the device is ready to save.

Try it

The preview next to the builder draws your device and updates as you edit. Switch it to Try it to use it:

• Press or hold the buttons (Shift+click holds), flip switches, turn knobs with the scroll wheel or arrow keys, and drag sliders.
• On a touchscreen, knob or e-ink board, the screen part works too.
• Tick the boxes under Pretend that… (labels waiting, printer problem, bridge offline, printing, roll confirmed) to see how the lights react.
• The list underneath says what Laberty would do, for example "Would print 3 waiting labels", "Blocked: needs a long press" or "Locked: Business plan".

Nothing prints and nothing changes: it's a dry run. Use live data borrows your real printer, roll and label names to make it look real.

On a saved device's page, Send for real makes each press really happen, after asking you first. It follows exactly the same rules as the device: a long press has to be held long enough, and Business commands stay locked on Home.

Wiring

The Wiring tab, and the Review & wiring step, show:

• a diagram with a coloured wire from each pin to its part
• a pin table (hover a part to highlight its wire)
• step-by-step instructions, a parts list and safety notes

Print wiring sheet gives a clean page to take to the workbench. You can also ask the assistant a question about the wiring; the pins and safety notes always come from Laberty's own wiring steps.

Always unplug the board while wiring. ESP32 pins are 3.3 V, so never connect 5 V to one. If a relay switches mains power, use an enclosed rated relay or a listed smart power strip, and have a qualified electrician do the mains side.

Save it and flash it

Press Save device and make its key. Laberty shows the device's key once: copy it into secrets.yaml along with your Wi-Fi details. Then either:

• flash the Laberty firmware for its kind from hardware/laberty-screen/ (see Laberty Screen), or
• download the device's ESPHome YAML and secrets.yaml.example from its page. The key is only read from secrets.yaml; the YAML never contains it.

What the buttons can do

A button, switch or knob can print the labels that are waiting, skip them, retry the last failed print, reprint the last label, print a test label (the same one Printers & stock sends), move to the next roll on the printer's list, or pause and resume the print bridge. Some things need setting up first:

• Saved labels (Admin → Devices → Saved labels) are labels one press prints. Write a few lines for a roll, such as Leftovers {date}: {date} and {time} are filled in when it prints. Or keep a copy of a label that already printed; Laberty keeps its own copy for as long as the saved label exists. Then pick it in a button's Print a saved label.
• Pausing the print bridge stops it picking up jobs; they wait in the queue. While it's paused, Print on the iPad opens the print dialog instead, and Admin → Print bridge says who paused it, with a Resume button. You can have it resume by itself after up to 8 hours.
• Webhooks (Business, Admin → Devices → Webhooks) let a held button or a switch call your own system. The device never calls it: Laberty sends a small signed message to your https address, with no names or addresses in it. Copy the secret when it's shown, because it's shown once. Send test tries it.
• A relay can power-cycle a printer. Hold the button, and the device switches the relay on for up to 2 seconds. On the device's page, Test asks the device to do it on its next check-in.
• A sensor can do something when a reading crosses a level. It happens once, and again only after the reading has come back past the level by the hysteresis you set.
• Confirming the roll "for sure" is a device's job. A roll switch or selector confirms the roll at each position. Or pick the roll on the screen or by turning the knob (Pick a roll), then press a button set to Confirm the roll. The pick is forgotten after 2 minutes. Pressing Confirm with nothing picked confirms the roll that's already recorded. The Roll picker + confirm button kit is a knob, one button and a green light that stays on while the roll is confirmed. On a screen with no confirm button, the screen's own Confirm records the roll as not sure. See Label stock: Confirmed or Not sure.

Every press is kept for 90 days: open the device and choose See the presses.

Change it later

Open the device from Admin → Devices:

• Edit device changes it. Every save is kept as a revision, and Roll back makes an older one live again.
• After you save, the page tells you whether the device needs flashing again:
  • Applied live: you only changed what the controls do or how the lights behave. The device uses the new setup on its next press, with nothing to flash.
  • Needs re-flash (controls or pins changed): you added or removed a part, or moved one to a different pin. Flash the device again. Until you do, the parts you changed don't work, and the rest keep working.
  • If you use the ESPHome YAML, download it again after adding a new gesture (a long press on a button that only had a press, for example), so the device listens for it.
• Rotate key makes a new key if you lose the old one or think someone has it. The old key stops working straight away.
• Settings turn the device off, set when it sleeps and set quiet hours.
• Revoke device removes it, along with its key.

If your plan changes, the device keeps working. It can still be saved as long as it doesn't grow, and commands your plan no longer includes stop working until you change plan again.