> Documentation index: https://nao-rs.lukaloehr.com/llms.txt, a list of every page in this documentation.

# LEDs

> REST API: LED groups, single LEDs, presets. Generated from the OpenAPI document.

## All LED overrides

`GET /v1/leds`

Groups that are `null` show the robot's own status. The groups and their LEDs are on [LEDs](https://nao-rs.lukaloehr.com/hardware/leds.md).

**Token:** required · **Lease:** not needed

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Current overrides | [LedStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledstatus) |
| 401 | Missing or wrong token | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/leds
```

## Replace all LED overrides

`PUT /v1/leds`

Groups left out or `null` go back to the robot.

**Token:** required · **Lease:** required (`Nao-Lease` header)

**Request body** (`application/json`)

[LedOverrides](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledoverrides). Every LED group's override. `null` (or absent) hands the group back to the robot.

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `chest` | [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no |  |
| `left_ear` | array of 10 × number or null | no | 10 brightness levels 0..1 (the ears are blue only). |
| `left_eye` | array of 8 × [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no | 8 colors, index 0 at the top, clockwise as seen from the front. |
| `left_foot` | [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no |  |
| `right_ear` | array of 10 × number or null | no |  |
| `right_eye` | array of 8 × [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no |  |
| `right_foot` | [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no |  |

```json
{"chest":"#00ff00","left_ear":[1,1,1,1,1,0,0,0,0,0],"left_foot":"#0050ff","right_foot":"#0050ff"}
```

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | All overrides replaced | [LedStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledstatus) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 422 | Invalid input | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

## Hand all LEDs back

`DELETE /v1/leds`

The robot's own status LEDs return.

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Status | Meaning | Body |
| --- | --- | --- |
| 204 | Every group handed back to the robot |  |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" http://$ROBOT:7702/v1/leds
```

## Running LED animations

`GET /v1/leds/animations`

**Token:** required · **Lease:** not needed

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Animations the ticker is running | array of [ActiveAnimation](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#activeanimation) |
| 401 | Missing or wrong token | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/leds/animations
```

## List LED presets

`GET /v1/leds/presets`

**Token:** required · **Lease:** not needed

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Available presets | array of [Preset](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#preset) |
| 401 | Missing or wrong token | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/leds/presets
```

## Apply an LED preset

`PUT /v1/leds/presets/{name}`

Sets every group at once.

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `name` | path | string | yes | Preset name from `GET /v1/leds/presets` |

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Preset applied to every group | [LedStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledstatus) |
| 404 | Unknown preset | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" http://$ROBOT:7702/v1/leds/presets/blue
```

## Set one LED group

`PUT /v1/leds/{group}`

Eyes take `color` or `colors` (8), ears `brightness` or `levels` (10), chest and feet `color`. `eyes`, `ears` and `feet` set both sides.

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `group` | path | [Group](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#group) | yes | LED group |

**Request body** (`application/json`)

[LedSetting](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledsetting). What to show on a group or a single LED. Exactly one field:
eyes take `color` or `colors` (8), ears take `brightness` or `levels` (10), chest and feet take
`color`; a single LED takes `color` (eye) or `brightness` (ear).

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `brightness` | number or null | no | One brightness 0..1 for every ear segment. |
| `color` | [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no | One color for every LED of the group. |
| `colors` | array of 8 × [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no | One color per eye segment (8). |
| `levels` | array of 10 × number or null | no | One brightness 0..1 per ear segment (10). |

```json
{"color":"#ff8800"}
```

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Group set | [LedStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledstatus) |
| 404 | Unknown group | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 422 | Invalid input (e.g. a color for an ear) | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" -H 'Content-Type: application/json' \
  -d '{"color": "#0055ff"}' http://$ROBOT:7702/v1/leds/eyes
```

## Hand one LED group back

`DELETE /v1/leds/{group}`

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `group` | path | [Group](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#group) | yes | LED group |

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Group handed back to the robot | [LedStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledstatus) |
| 404 | Unknown group | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" http://$ROBOT:7702/v1/leds/eyes
```

## Animate an LED group

`PUT /v1/leds/{group}/animation`

Breathe, blink, rainbow (not ears) or progress, computed on the robot at 20 Hz. Replaces an animation on an overlapping group. Any LED write to the group cancels it, and it ends with the lease. Animation frames are no heartbeat: keep sending heartbeats.

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `group` | path | [Group](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#group) | yes | LED group |

**Request body** (`application/json`)

[LedAnimation](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledanimation). An animation for one group.

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `brightness` | number or null | no | Ears: peak brightness 0..1 (default 1). Not for the color groups. |
| `color` | [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no | Eyes, chest and feet (default white). Not for ears, which are blue only. |
| `kind` | [AnimationKind](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#animationkind) | yes |  |
| `period_ms` | integer or null | no | One cycle, 100 to 60000 ms (default: breathe 3000, blink 1000, rainbow 4000). (100 to 60000) |
| `value` | number or null | no | Progress only (required there): 0..1. |

```json
{"color":"#0050ff","kind":"breathe","period_ms":3000}
```

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Animation running | array of [ActiveAnimation](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#activeanimation) |
| 404 | Unknown group | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 422 | Invalid input (e.g. a rainbow on the ears) | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" -H 'Content-Type: application/json' \
  -d '{"kind": "breathe", "color": "#0050ff", "period_ms": 3000}' http://$ROBOT:7702/v1/leds/eyes/animation
```

## Stop an LED animation

`DELETE /v1/leds/{group}/animation`

The group keeps its last frame; `DELETE /v1/leds/{group}` hands it back to the robot.

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `group` | path | [Group](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#group) | yes | LED group |

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Animations still running | array of [ActiveAnimation](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#activeanimation) |
| 404 | Unknown group | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" http://$ROBOT:7702/v1/leds/eyes/animation
```

## Set a single LED

`PUT /v1/leds/{group}/{index}`

One eye segment (`color`, index 0 to 7 from the top, clockwise as seen from the front) or one ear segment (`brightness`, index 0 to 9). The index order is on [LEDs](https://nao-rs.lukaloehr.com/hardware/leds.md).

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `group` | path | [Group](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#group) | yes | left_eye, right_eye, left_ear or right_ear |
| `index` | path | integer | yes | Segment: eyes 0..7 from the top clockwise, ears 0..9 |

**Request body** (`application/json`)

[LedSetting](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledsetting). What to show on a group or a single LED. Exactly one field:
eyes take `color` or `colors` (8), ears take `brightness` or `levels` (10), chest and feet take
`color`; a single LED takes `color` (eye) or `brightness` (ear).

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `brightness` | number or null | no | One brightness 0..1 for every ear segment. |
| `color` | [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no | One color for every LED of the group. |
| `colors` | array of 8 × [Color](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#color) or null | no | One color per eye segment (8). |
| `levels` | array of 10 × number or null | no | One brightness 0..1 per ear segment (10). |

```json
{"color":"#ff8800"}
```

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Segment set | [LedStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#ledstatus) |
| 404 | Unknown group | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 422 | Invalid input (index out of range, wrong kind of value) | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" -H 'Content-Type: application/json' \
  -d '{"color": "#ff0000"}' http://$ROBOT:7702/v1/leds/left_eye/0
```

## Related topics

- [REST API](https://nao-rs.lukaloehr.com/reference/rest-api.md)
- [System](https://nao-rs.lukaloehr.com/reference/rest-api/system.md)
- [Robot](https://nao-rs.lukaloehr.com/reference/rest-api/robot.md)
- [State](https://nao-rs.lukaloehr.com/reference/rest-api/state.md)
- [Events](https://nao-rs.lukaloehr.com/reference/rest-api/events.md)
- [Safety](https://nao-rs.lukaloehr.com/reference/rest-api/safety.md)
- [Control](https://nao-rs.lukaloehr.com/reference/rest-api/control.md)
- [Audio](https://nao-rs.lukaloehr.com/reference/rest-api/audio.md)
- [Cameras](https://nao-rs.lukaloehr.com/reference/rest-api/cameras.md)
- [Power](https://nao-rs.lukaloehr.com/reference/rest-api/power.md)
- [Motion](https://nao-rs.lukaloehr.com/reference/rest-api/motion.md)
- [Schemas](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md)
- Previous: [Control](https://nao-rs.lukaloehr.com/reference/rest-api/control.md)
- Next: [Audio](https://nao-rs.lukaloehr.com/reference/rest-api/audio.md)