---
title: Pixel LED Address Planner
description: Plan pixel LED runs, outputs and universe addresses for a lighting project.
canonical: https://ledyi.com/tools/pixel-led-address-planner
updatedAt: 2026-10-23T23:54:47Z
---

# Pixel LED Address Planner

Plan pixel LED runs, outputs and universe addresses for a lighting project.

## For AI agents: instructions and calculation APIs

Read the tool instructions in Markdown and the request/response schemas in OpenAPI. These public calculation APIs run the same models as the web and offline calculators. No account, API key or Turnstile is required.

- [Pixel LED Address Planner — Full tool instructions (Markdown)](https://ledyi.com/tools/pixel-led-address-planner.md)
- [OpenAPI contract](https://ledyi.com/openapi.json)
- [Agent site index](https://ledyi.com/llms.txt)

Your agent needs an HTTP tool permitted to send POST requests. Reading this page or importing OpenAPI does not automatically grant execution access.

### Pixel LED Address Planner

```
POST /api/tools/v1/pixel-plan
Content-Type: application/json
```

Plan independently wired pixel LED runs. Enter independently addressable physical pixels, not LED packages. Each run instance uses one output. Grouping reduces control points and input channels; it does not reduce physical pixel load, power or wiring requirements.

### Pixel LED address planning

Send the complete version=1 project object below, the same format used by Download editable project. All fields are required, including unique run IDs and explicit null controller limits when unknown. The example is four 200-pixel RGB runs, 8-bit control, 512 slots and a new universe per output. It produces 800 physical pixels, 2,400 channels, 4 outputs and 8 universes.

| Field | Type and constraints | Meaning |
| --- | --- | --- |
| version (Required) | {"type":"number","enum":[1]} |  |
| projectName (Required) | {"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\u0000-\\u001f\\u007f]*$"} | Project name |
| protocol (Required) | {"type":"string","enum":["sacn","artnet","dmx"]} |  |
| startUniverse (Required) | {"type":"integer","minimum":0,"maximum":63999} | Starting Universe |
| startChannel (Required) | {"type":"integer","minimum":1,"maximum":512} | Starting channel |
| universeSize (Required) | {"type":"number","enum":[510,512]} |  |
| boundary (Required) | {"type":"string","enum":["whole","continuous"]} |  |
| allocation (Required) | {"type":"string","enum":["port","compact"]} |  |
| inputBits (Required) | {"type":"number","enum":[8,16]} |  |
| controller (Required) | {"type":"object","additionalProperties":false} |  |
| controller.name (Required) | {"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\u0000-\\u001f\\u007f]*$"} | Controller name |
| controller.ports (Required) | {"anyOf":[{"description":"Controller output count","type":"integer","minimum":1,"maximum":4096},{"type":"null"}]} |  |
| controller.maxPixelsPerPort (Required) | {"anyOf":[{"description":"Maximum physical pixels per output","type":"integer","minimum":1,"maximum":100000000},{"type":"null"}]} |  |
| controller.maxTotalPixels (Required) | {"anyOf":[{"description":"Maximum total physical pixels","type":"integer","minimum":1,"maximum":100000000},{"type":"null"}]} |  |
| controller.maxUniverses (Required) | {"anyOf":[{"description":"Maximum input Universes","type":"integer","minimum":1,"maximum":63999},{"type":"null"}]} |  |
| runs (Required) | {"type":"array","minItems":1,"maxItems":64} |  |
| runs[].id (Required) | {"type":"string","minLength":1,"maxLength":80,"pattern":"^[^\\u0000-\\u001f\\u007f]*$"} | Strip identifier |
| runs[].name (Required) | {"type":"string","minLength":1,"maxLength":80,"pattern":"^[^\\u0000-\\u001f\\u007f]*$"} | Strip name |
| runs[].pixels (Required) | {"type":"integer","minimum":1,"maximum":100000} | Physical pixels per strip |
| runs[].color (Required) | {"type":"string","enum":["rgb","rgbw"]} |  |
| runs[].group (Required) | {"type":"integer","minimum":1,"maximum":100000} | Physical pixels per control group |
| runs[].quantity (Required) | {"type":"integer","minimum":1,"maximum":64} | Quantity |

```
{
  "version": 1,
  "projectName": "My pixel project",
  "protocol": "sacn",
  "startUniverse": 1,
  "startChannel": 1,
  "universeSize": 512,
  "boundary": "whole",
  "allocation": "port",
  "inputBits": 8,
  "controller": {
    "name": "Custom controller",
    "ports": null,
    "maxPixelsPerPort": null,
    "maxTotalPixels": null,
    "maxUniverses": null
  },
  "runs": [
    {
      "id": "run-1",
      "name": "Ceiling cove",
      "pixels": 200,
      "color": "rgb",
      "group": 1,
      "quantity": 4
    }
  ]
}
```

### Reading the result

Control points per run = ceil(pixels / group). Input footprint = 3 for RGB or 4 for RGBW, multiplied by inputBits / 8. Channels = control points × footprint × quantity. Grouping restarts per output and retains a short final group. Whole-pixel mapping skips insufficient space at the end of a universe; continuous mapping may split colour channels. Native DMX512 runs must fit within one physical output.

result.ok=true and status=ready mean the address plan fits the rules and the limits you supplied. result contains summary, every output in ports, complete universe fragments, errors and warnings. A valid request with capacity, native-DMX or universe-range issues returns HTTP 200 with status=needs-attention, ok=false and links.share=null. Keep every issue and any unmapped output visible; never present that response as a complete usable plan. summary.limitsVerified=false means at least one controller capacity is unchecked. Stable issue codes include PIXEL\_NATIVE\_DMX\_OVERFLOW, PIXEL\_UNIVERSE\_RANGE\_EXCEEDED and PIXEL\_CONTROLLER\_CAPACITY\_EXCEEDED; each issue has field and message.

Missing fields, numeric strings, unknown fields, duplicate run IDs, non-integers and unsupported combinations return 422. Use 1–64 run rows, at most 128 output instances and 2000000 input channels in total. startChannel cannot exceed universeSize. Art-Net uses actual numeric Port-Addresses 0–32767; sACN uses 1–63999. A native DMX output cannot use continuous boundary splitting. Invalid requests never become the default project.

Open links.share to restore all project inputs in the browser. Save inputs as JSON and use Open saved plan to restore them in the web or offline calculator. Check controller mapping support, power, wiring, pixel compatibility and refresh rate separately. CSV is a generic configuration reference, not a universal controller import. Web and offline exports keep using the same local model; the offline download endpoint is not a calculation API.

### Request limits and errors

Every success carries apiVersion, a server-generated requestId, operation, normalized inputs, result, warnings and links (tool, markdown, openapi, share). requestId also appears in X-Request-Id. The domain result is deterministic; the request ID changes. Preserve warnings and special statuses when explaining results.

Send uncompressed application/json with strict types and no query parameters. Indoor lighting bodies are limited to 16 KiB; driver-match bodies to 16 KiB; battery bodies to 16 KiB; voltage bodies to 16 KiB; resistor bodies to 16 KiB; spectrum bodies to 16 KiB; DMX bodies to 1024 KiB and 1000 fixtures; pixel bodies to 64 KiB, 64 run rows, 128 outputs and 2000000 channels. DALI bodies are limited to 64 KiB, 24 rows and 512 devices. Illuminance bodies are limited to 16 KiB and 400 planned points. Photometry bodies are limited to 1024 KiB with up to 4 files and 16 by 721 query directions per file. Lighting-cost bodies are limited to 64 KiB with up to 20 groups in each scenario. Body reading expires after 5 seconds. Complete success JSON is bounded to 4 MiB. GET/HEAD return 405; OPTIONS returns 204. Source responses are no-store. Anonymous browser CORS permits POST/OPTIONS and Content-Type with credentials omitted.

Tool POST requests and ordinary page requests share 120 requests per 60 seconds per IP/Cloudflare location; mitigation lasts 60 seconds. Heavy tool use can temporarily block pages from the same source. This is not an independent or globally exact API quota. Inquiry/search use their existing separate rule. Tool POST requests do not inherit the company-page or verified-bot exemption.

Source errors use application/problem+json with status, stable code, requestId and at most one invalidParams JSON pointer. 400: malformed JSON/query; 405: method; 408: body timeout; 413: body limit; 415: media/encoding; 422: parameter/domain error; 500/503: service failure. Fix invalid inputs rather than retrying or changing engineering facts. For 429 or transient failures, use at most two retries with backoff and jitter, honoring Retry-After when present.

Cloudflare can return 403/429/5xx before the application, sometimes as HTML without CORS or Retry-After. Check HTTP status and Content-Type before parsing JSON. A browser may see only a network error. Do not present an error or an older result as a successful new calculation.

Calculations do not create inquiries, send emails, call a language model or store project results. Operational logs exclude fixture labels, groups and request bodies. Existing network/access logs still apply. Submit a quotation request only when the user asks, using the separate inquiry contract and buyer confirmation flow.

### Warning codes

| Field | Meaning |
| --- | --- |
| PIXEL_CONTROLLER_LIMIT_UNCHECKED | A controller capacity was not supplied. Check each warning field; null does not mean unlimited or verified. |
| PIXEL_PARTIAL_GROUP | The final control group is shorter than group. Confirm that the controller supports a partial group. |
| PIXEL_GROUPING_REQUIRES_SUPPORT | Confirm support for the requested grouping. Physical pixel load is unchanged. |
| PIXEL_OUTPUT_OFFSETS_REQUIRE_SUPPORT | Compact allocation requires independent universe and channel offsets per output. |
| PIXEL_SPLIT_BOUNDARY | Colour channels cross a universe boundary; sender and controller must share this mapping rule. |
| PIXEL_16BIT_INPUT_REQUIRES_SUPPORT | 16-bit input requires explicit support; LED-chip internal PWM depth does not establish input footprint. |

### Error codes

```
TOOLS_INVALID_JSON
TOOLS_QUERY_UNSUPPORTED
TOOLS_METHOD_NOT_ALLOWED
TOOLS_BODY_TIMEOUT
TOOLS_BODY_TOO_LARGE
TOOLS_MEDIA_TYPE_UNSUPPORTED
TOOLS_CONTENT_ENCODING_UNSUPPORTED
TOOLS_INPUT_INVALID
TOOLS_NUMERIC_DOMAIN_UNSUPPORTED
TOOLS_INTERNAL_ERROR
TOOLS_SERVICE_UNAVAILABLE
DMX_INPUT_INVALID
DMX_ADDRESS_NOT_ENCODABLE
DMX_CHANNEL_RANGE_EXCEEDED
DMX_SPACING_OVERLAP
DMX_UNIVERSE_RANGE_EXCEEDED
PHOTOMETRY_FILE_INVALID
PHOTOMETRY_FILE_UNSUPPORTED
PHOTOMETRY_LIMIT_EXCEEDED
```
