Deployment Best Practices

Arrows & Display Conventions

A predictable display is easier to scan during a busy pick. Define a simple convention for arrows, line content, text length, and color, then use it throughout the workflow.

• Automatic arrows — Use the Location Alias API to associate each logical location with a direction. When you send a command to an alias, Big Block displays the matching arrow automatically, so your application does not need to choose an arrow for every command.
• Display lines — Consistency matters more than one universal layout. Decide what Line 1 and Line 2 mean in your workflow, then keep those roles the same on every display. Send the pick quantity through the dedicated quantity field so it appears in the quantity box instead of consuming a text line.
• Font size — Keep each message as short as possible. Shorter text can render at a larger size, making the most important information easier to read at a glance.
• Color coding — Color most often identifies the picker: each picker follows their preferred color. Assign colors that are easy to distinguish, and be careful with similar-looking choices such as magenta and red. Confirm the assignments with the pickers under the lighting used in the work area.

Prefer the Orders API for Order-Based Picking

If your workflow begins with orders, shipments, and items, use the Orders API instead of rebuilding that structure with individual device calls. Big Block can manage the fulfillment state while your integration creates and launches the work.

• Start with a working picker interface. Voodoo's Android picking app provides a prebuilt GUI for work uploaded through the Orders API.
• Keep hardware costs flexible. The app can run on a potentially inexpensive Android handheld scanner, so you do not need to design dedicated picker hardware.
• Keep order state in one place. Model orders, shipments, items, requested quantities, and fulfillment progress in Big Block instead of duplicating that logic in device commands.

These videos introduce the Android picking app and then walk through its interface in more detail.

Reuse Integration Code Before Building

Check the Integration Examples before starting with an empty project. Choose the closest platform or event pattern, fork it, and run its existing tests with safe sample data before changing the mappings.

• Preserve proven authentication, retry, idempotency, logging, and callback patterns unless your requirements demand a change.
• Use the Voodoo Oracle to explain the code, identify missing requirements, adapt it, add tests, and prepare repeatable deployment instructions.
• Contribute broadly useful fixes, mappings, tests, and documentation back to the repository when possible.

Pilot Design

A well-designed pilot validates both the technology and the workflow. Follow these guidelines:

1. Start small — Deploy 10–25 Devices on a single aisle or zone. This is enough to prove throughput improvements without requiring full warehouse integration.
2. Pick a representative workflow — Choose a process that reflects your highest-volume or most error-prone workflow. The pilot should demonstrate measurable improvement.
3. Measure baseline first — Record current pick rates, error rates, and training time before deploying Turbos. You need a comparison point.
4. Run for at least 2 weeks — Operators need time to adjust. First-day metrics are not representative of steady-state performance.
5. Assign a champion — Designate one person on-site who owns the pilot, collects feedback, and communicates with Voodoo support.

REST vs QueryString Integration

Voodoo supports two integration approaches. Use REST when your environment supports it, and fall back to QueryString for simpler or more constrained clients:

import requests

url = "https://www.voodoodevices.com/api/device/D4F660:AFA0CB/"
headers = {
    "API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "line1": "SKU-1234",
    "quantity": 5,
    "color": "green",
    "arrow": "left"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

curl -X POST "https://www.voodoodevices.com/api/device/D4F660:AFA0CB/" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "SKU-1234",
    "quantity": 5,
    "color": "green",
    "arrow": "left"
  }'

# Light up device D4F660:AFA0CB with SKU and quantity
curl -H "API-KEY: YOUR_KEY" \
  "https://www.voodoodevices.com/api/D4F660:AFA0CB/message/SKU-1234~Qty:5/"

LED Color & Light Usage

LEDs on Cloud Display Devices provide visual cues that operators can see from a distance. There are two common ways to use color, and it is important not to mix them in the same workflow.

• Picker-assigned colors — In many deployments, each picker follows one color so multiple pickers can work in the same area at the same time. If you use this model, let each picker choose the color they will follow. Do not assume everyone sees every color equally well.
• Status colors — In other workflows, colors communicate meaning. A common pattern is Green = active pick, Red = error or alert, Yellow/Amber = caution, and Blue = informational or replenishment.
• Off — No action required. Don't leave LEDs on when not in use — it creates visual noise.

Battery Optimization

Cloud Display Devices are designed for long battery life, but display and LED usage patterns affect longevity. Follow these guidelines to maximize uptime:

• Don't worry about the e-paper display — The display itself does not consume extra power just because text remains visible. Battery drain is mainly caused by LEDs and radio activity.
• Turn off LEDs when work is done — The LED turns off when the operator pushes the button or when you send a Kill command through the REST API. Once the LED is off, the device returns to its static display behavior as described in the Commands vs. Statics guide.
• Monitor battery levels — Enroll your email address to receive notifications or use the device endpoint to check battery levels proactively. Replace or recharge before levels drop below 20%.

Request Efficiency

These practices help your integration move updates through the server more efficiently, especially when many devices are involved.

• Use the plural devices endpoint for bulk work — You can send bulk commands or bulk static updates to /api/devices/ as a JSON array. This can save time when updating many devices together.
• Reuse connections in your code — The biggest time savings usually come from reusing the same HTTP connection or session object for multiple requests instead of opening a new connection each time and paying for DNS lookup, TLS setup, and other connection overhead.

Operational Guardrails

These guardrails help prevent common deployment issues:

• Error handling — Always check HTTP response codes. A 200 means the server accepted the command; it doesn't guarantee the Turbo received it. Use the closed-loop system for confirmation.
• Location naming — DeviceIDs are assigned at the factory. What you control is the location naming in your WMS, Big Block, or alias mapping. Use a consistent location format such as Zone-Aisle-Position (e.g., A-03-12).
• Test in staging — Where possible, test integration changes against www.voodoodevices.com (hosted, multi-tenant) before deploying to self-hosted Big Block in production.