Voodoo RoboticsDeveloper Portal

Getting Started

Many teams go from unboxing to first lit device in ~30 minutes (network/environment dependent).

Quickstart Checklist

Before you write any code, make sure you have the following ready:

  1. 1
    Starter Kit or devices — You need at least one Cloud Display Device and one Turbo. Most companies start with a Starter Kit (commonly 10 devices + 1 Turbo + 1 cloud account).
  2. 2
    User account — Your account on www.voodoodevices.com or your Big Block Server. Included with the Starter Kit.
  3. 3
    Network access — WiFi or Ethernet for the Turbo to reach the server. See Network Prerequisites below.
  4. 4
    Batteries — Two AAA alkaline batteries per device (not included).
  5. 5
    API credentials — API-KEY (simplest), or session login (username/password + session cookie + CSRF token for POSTs).

Network Prerequisites

Turbos are the bridge between your network and the Cloud Display Devices. Each Turbo needs:

  • WiFi or Ethernet — Turbos support DHCP out of the box. Connect via Ethernet cable or configure WiFi through the Turbo's built-in touchscreen.
  • Power — AC adapter (included) or Power over Ethernet (PoE, IEEE 802.3af; PoE+ depending on switch/injector and model). PoE supplies both power and network over a single cable — never use the AC adapter and PoE simultaneously.
  • Placement — Mount on a wall or pillar at a height that's out of reach but not out of range (typically 8–12 feet). Plan roughly 50–100 ft between Turbos depending on racks, walls, and RF noise; validate with a quick walk test.
  • Firewall (cloud only) — Allow outbound HTTPS to www.voodoodevices.com. Turbos may also need outbound access for OS security updates (Ubuntu security repos).

Overlapping Coverage

Multiple Turbos with overlapping coverage areas improve both reliability and speed. Devices automatically communicate with the nearest available Turbo, and more Turbos mean faster response times.

Choose Your Integration Path

Voodoo offers two APIs. Choose based on your needs:

REST API (Recommended)

Full JSON-based API with support for bulk updates, locations, orders, sequences, and closed-loop confirmations. Use this for production.

import requests
session = requests.Session()
url = "https://www.voodoodevices.com/api/"
session.post(url + "device/E8D008:619874/",
    headers={'API-KEY': 'your-key'},
    json={'command': 'flash',
          'line1': 'Hello',
          'line2': 'World',
          'seconds': 60})

QueryString API (Simple GET)

Construct a URL with parameters and issue a GET request. No JSON parsing required. Ideal for systems with limited HTTP capabilities or for quick testing.

# Light up device E8D008:619874 with "Hello"
curl -H "API-KEY: your-api-key" \
  "https://www.voodoodevices.com/api/E8D008:619874/message/Hello~World/"

Note

Both hit the same server. REST supports full auth options (API-KEY, session, OAuth2, etc.). The simple URL method is typically used for quick evaluation. You can switch to REST at any time — no migration needed.

Your First Test

Follow these steps to light up your first device:

Step 1: Set Up Hardware

Insert two AAA alkaline batteries into each Cloud Display Device. Power on your Turbo using the included AC adapter (USB-C) — you can also connect an Ethernet cable for networking. Alternatively, use a PoE switch or injector to supply both power and network over a single Ethernet cable, with no AC adapter needed. Never use the AC adapter and PoE simultaneously.

Step 2: Configure Your Turbo

The Turbo needs to know your network credentials and server endpoint before it can relay commands to devices.

The interface depends on your Turbo model, but the steps are the same for both: the Turbo POE-T has a built-in touchscreen (no external monitor or keyboard needed), while the Regular Turbo requires a monitor, mouse, and keyboard for initial setup only — disconnect them once configured.
  1. Connect WiFi (skip if using Ethernet) — tap Connect WiFi, select your network, and enter your WiFi password.
  2. Connect to server — tap Connect Server and enter your username and password from your voodoodevices.com account (or a dedicated API-User account you've created). If you're running self-hosted Big Block, enter your server endpoint in the Server Endpoint field (e.g. https://bblock.yourcompany.com/api).
  3. Verify status — the idle screen should show Status: okay and DB Status: okay. If DB Status is not okay, check outbound HTTPS connectivity from the Turbo (firewall issue).

Step 3: Log In to Your Server

Go to https://www.voodoodevices.com (or your self-hosted Big Block URL) and log in with your account credentials. You should see your Turbo and devices listed.

Step 4: Find Your Device ID

Each device has a unique DeviceID in the format FFFFFF:EEEEEE. You can find this in the Big Block GUI or by querying the device list endpoint:

import requests
url = "https://www.voodoodevices.com/api/"
headers = {'API-KEY': 'your-api-key'}

response = requests.get(url + "device/", headers=headers)
device_ids = response.json()
for device_id in device_ids:
    print(device_id)

Step 5: Send Your First Command

Use the device ID from Step 4 to send a flash command. The device should light up and display your message:

import requests

url = "https://www.voodoodevices.com/api/"
headers = {'API-KEY': 'your-api-key'}
device_id = "E8D008:619874"  # Replace with your device ID

response = requests.post(
    url + f"device/{device_id}/",
    headers=headers,
    json={
        'command': 'flash',
        'line1': 'Hello',
        'line2': 'World',
        'color': 'g',       # Green LED
        'sound': '15,c5,4', # Beep
        'seconds': 60       # Timeout after 60 seconds
    }
)
print(response.status_code)

Common Pitfalls

❌ Forgetting the trailing slash

API endpoints require a trailing slash. Use /api/device/FFFFFF:EEEEEE/ not /api/device/FFFFFF:EEEEEE.

❌ Missing the referer header (Session auth)

When using Session-based authentication, POST requests require both the x-csrf-token and referer headers. GET requests do not need these.

❌ Using HTTP instead of HTTPS

Always use HTTPS for production. Basic auth over HTTP is completely insecure and disabled by default on most deployments.

❌ Turbo not within range

Cloud Display Devices communicate via radio with Turbos. Range is site-dependent — plan for 50–100 ft depending on racks, walls, and RF noise. If a device doesn't respond, check that a powered Turbo is within range.

❌ Dead batteries

Devices run on two AAA batteries. Check voltage via the API or Big Block GUI. Alkaline batteries are recommended for best performance.

Understanding Commands vs. Statics

The command field and seconds parameter work together to create time-bound work instructions. When a command expires or is acknowledged, devices fall back to their persistent statics (background state). Understanding this distinction is essential for reliable integrations. See the Commands vs. Statics Quick Reference for details.

What's Next?

Once you've lit up your first device, explore these topics to build out your integration:

Next Steps

Commands vs. Statics

Essential guide to command vs. static behavior

Authentication

Configure API-KEY, Session, or OAuth2 authentication

REST API Overview

Full endpoint reference with examples

Starter Kit

What's included and what you can validate

Devices & Networking

Turbo placement, power, and troubleshooting