Commands vs. Statics — Quick Reference

1. Two Execution Paths: Commands vs. Statics

Every API request is classified into exactly one of these paths:

• Command execution (dynamic, time-bound)
• Static update (persistent background state)

Which path is taken is determined by what fields are present, not by intent.

Video Walkthrough

Watch commands and static messages being sent through the REST API, then use the detailed rules below when you build your integration.

2. Commands (Dynamic, Time-Bound)

Commands represent active work that a human is expected to complete.

What Makes a Request a Command

A request is treated as a command if either of the following is true:

• A command field is present, or
• Any line1–line5 field is present (the system will implicitly convert this into a flash command)

Command Behavior

• Commands expire after seconds
• On button press → ACK → command is cleared
• On timeout → NACK → command is cleared
• After clearing, the device immediately falls back to its statics

Example Command

{
  "command": "display",
  "line1": "Pack Order 12345",
  "line2": "Qty: 3",
  "color": "blue",
  "seconds": 3600
}

Important Rules

• seconds = 0 means never timeout (LED stays on until batteries fail)
• Long-running commands are allowed but consume battery continuously
• Commands are not persistent state and are never remembered after ACK/NACK

3. Statics (Persistent Background State)

Statics define what the device displays when no command is active.

What Makes a Request a Static Update

A request is treated as a static update when:

• No command is present, and
• At least one of statica–statice, locationoverride, brightness, or similar settings is present

If any static line is provided, all static lines are normalized internally to ensure consistent display behavior.

Static Behavior

• Statics never timeout
• They persist until explicitly changed
• They do not generate ACKs or NACKs
• They consume minimal battery (no LED usage)

Example Static Update

{
  "locationoverride": "PutWall 1|Cubby 34",
  "statica": "Order 34455",
  "staticb": "Waiting for Pack",
  "arrow": "up"
}

4. seconds vs. displaytimeout (Not Related)

These parameters control completely different systems.

Key Clarification

• displaytimeout never affects LEDs
• displaytimeout cannot cause NACKs
• It only controls how long identifying information overlays statics

5. Settings Are Not Commands

Some fields are settings, not actions:

• brightness
• locationoverride
• displaytimeout
• statica–statice

These are remembered by the device and reused automatically.

6. Automatic Normalization (What the Platform Helps With)

Behind the scenes, the platform:

• Converts colors, arrows, icons, quantities, barcodes, and QR codes into device-native representations
• Automatically assigns arrows when a location is known
• Enforces maximum line lengths
• Prevents invalid combinations (e.g., statics inside commands)
• Ensures commands and statics remain logically separate

This allows integrators to send human-readable JSON while devices receive optimized instructions.

7. Recommended Pattern for Long-Lived States

❌ Anti-Pattern

• Very large seconds values (hours/days)
• seconds = 0 to handle pauses in work

✅ Recommended Pattern

1. Use commands to drive active work
2. Allow commands to timeout naturally
3. On NACK, replace with a static message (e.g., "Waiting for Pack")
4. Clear or update statics when work resumes

This approach:

• Preserves battery life
• Avoids surprise NACKs
• Produces predictable device behavior

8. Advanced Pattern: CALL-Based Reissue

Some integrations intentionally:

1. Let commands timeout
2. Display a static message instructing a long button press
3. Receive a call event while the device is idle
4. Re-issue the command in response

This ensures explicit human intent and avoids silent retries.

Field Classification Table

A) Path Selectors (decide whether it's a Command or a Static update)

B) Command Payload Fields (meaningful when it's a command)

C) Static Payload Fields (persistent settings + background display)

D) "Convenience" Fields (interpreted differently depending on Command vs Static)

These are the sneaky ones: they're accepted in both worlds, and might or might not persist.

Practical takeaway: these "convenience" fields behave like extra lines in a command, but like persistent statics in a static update.

E) Fields Intentionally Suppressed/Ignored in Commands

Put Wall / Pack Wall Worked Example

Below is a Put Wall / Pack Wall worked example mapped end-to-end, using commands for short-lived actions and statics for long-lived state.

A. One-time provisioning per cubby (both sides)

Do this once when installing / mapping devices.

{
  "locationoverride": "PutWall 1 | Cubby 34",
  "displaytimeout": 15,
  "brightness": 100
}

What it means: Device always knows its putwall/cubby identity when idle. When someone taps the button while idle, it will briefly show DeviceID/location for 15s, then revert.

B. Put Side workflow (fast action)

Goal: Light the Put Side device briefly while the sorter drops units.

{
  "command": "flash",
  "line1": "PUT: Order 1959690",
  "line2": "Qty: 2",
  "color": "blue",
  "seconds": 60,
  "nonce": "1959690"
}

C. Pack Side workflow (may sit for hours)

Goal: If items are sitting in cubby waiting for packing, the device should keep showing state without draining batteries or generating NACK noise.

{
  "locationoverride": "PutWall 1 | Cubby 34",
  "statica": "READY TO PACK",
  "staticb": "Order 1959690",
  "staticc": "Units: 2",
  "arrow": "up"
}

D. Trigger the packer at the moment packing should happen

When packing actually begins (or when you want to actively draw attention), use a command on Pack Side.

{
  "command": "display",
  "line1": "PACK NOW",
  "line2": "Order 1959690",
  "line3": "Units: 2",
  "color": "green",
  "seconds": 900,
  "nonce": "1959690-pack"
}

E. What to do on ACK (packing completed)

When you get ACK for the pack command, you typically want to change the idle state.

{
  "statica": "",
  "staticb": "",
  "staticc": "",
  "staticd": "",
  "statice": ""
}

{
  "statica": "PACK COMPLETE",
  "staticb": "Order 1959690",
  "staticc": "Good to ship"
}

F. What to do on NACK (packing didn't happen in time)

This is where Pack Side differs from Put Side. If the pack command times out (NACK), don't keep reissuing a long-running command. Instead:

{
  "statica": "WAITING FOR PACK",
  "staticb": "Order 1959690",
  "staticc": "Units: 2"
}

G. Optional advanced pattern: CALL-based reissue (human intent)

If you want the packer to explicitly say "I'm here, re-light it":

{
  "statica": "HOLD BUTTON 4s",
  "staticb": "to re-light pack",
  "staticc": "Order 1959690",
  "unsolicitedNonce": "reissueID-122298393"
}

On multi-button devices, unsolicited plus and minus presses sendcall_up and call_down only when no command is being displayed. During an active command, those same buttons are treated as quantity adjustments instead of unsolicited callbacks.