---
title: Busy Tag AT command reference (firmware 3.0)
description: "This page lists the USB AT commands for the Busy Tag with Wi-Fi (hardware 2.0, firmware 3.0). Use them to control the LED bar and screen, set up Wi-Fi, and manage files from your own code or a serial terminal.…"
url: "https://luxafor.com/help/developers/busy-tag-at-commands-firmware-3-0/"
updated: "2026-11-16"
category: Developers
---

# Busy Tag AT command reference (firmware 3.0)

This page lists the USB AT commands for the Busy Tag with Wi-Fi (hardware 2.0, firmware 3.0). Use them to control the LED bar and screen, set up Wi-Fi, and manage files from your own code or a serial terminal.

## Before you start

- A Busy Tag with Wi-Fi hardware (HW 2.0) and firmware 3.0. To check, send `AT+GHV` and `AT+GFV` (see [Read device information](https://luxafor.com/help/developers/busy-tag-at-commands-firmware-3-0/#read-device-information)).
- A USB cable that carries data, not a charge-only cable.
- A serial terminal program, or your own code (see [Code examples](https://luxafor.com/help/developers/busy-tag-at-commands-firmware-3-0/#code-examples)).

Firmware 3.0 adds these on top of the 2.x features: Wi-Fi station and access point networking, a cloud WebSocket connection, HTTP(S) file download and upload, a local HTTP server, an on-screen setup QR code, and a status toolbar you can configure.

## What you can control

- **RGB LED bar:** solid colors, custom multi-step patterns, and 25 built-in animations.
- **LCD display:** stored PNG and GIF images, solid color fills, and a status toolbar you can configure (Wi-Fi, temperature, clock).
- **Wi-Fi:** station, access point, and combined STA+AP modes, with scanning and diagnostics.
- **Cloud connection:** a WebSocket client with Ed25519 device authentication, remote commands, and event reporting.
- **Network file transfer:** direct HTTP(S) downloads to storage (including OTA firmware) and uploads of stored files to the cloud.
- **Local HTTP server:** REST access to the same command set on the local network. The mobile apps use it in AP mode.
- **USB CDC interface:** the complete AT command set for control and file transfer.
- **Internal storage:** a FAT file system with wear leveling for images and data files.
- **Power management:** dynamic frequency scaling, Wi-Fi modem sleep, and idle display dimming.
- **Temperature and diagnostics:** internal die temperature, reset reasons, and chip, bootloader and USB line state info.

## Hardware

| Component | Specification |
| --- | --- |
| MCU | Dual-core Xtensa LX7, 240 MHz, Wi-Fi 802.11 b/g/n |
| Framework | ESP-IDF v5.x |
| Storage | Internal flash, FAT with wear leveling |
| Display | LCD, PNG + animated GIF support |
| LED | RGB LED bar (7 addressable positions) |
| Interface | USB CDC, Wi-Fi (STA / AP / STA+AP), local HTTP server |
| Hardware version | 2.0 (reported by `AT+GHV`) |

## Connect over USB

Connect the Busy Tag to your computer with a USB cable. The Busy Tag shows up as a USB CDC serial port. Open it with any serial terminal.

#### Serial settings

| Setting | Value |
| --- | --- |
| Baudrate | 460,800 bps |
| Data bits | 8 |
| Stop bits | 1 |
| Parity | None |
| Flow control | None |

#### Test the connection

Send `AT`. The Busy Tag answers `OK`. In all examples on this page, a line that starts with `>` is the command you send. The other lines are the replies.

```
> AT
OK
```

#### Command format

| Type | Format |
| --- | --- |
| Read or query | `AT+<CMD>?` or `AT+<CMD>` |
| Write or set | `AT+<CMD>=<parameters>` |
| Action | `AT+<CMD>` |

End every command line with `rn` (CR+LF). Commands are case-insensitive.

#### Reply format

| Reply | Format and meaning |
| --- | --- |
| Data and success | A `+<PREFIX>:<data>` line, then `OK` |
| Simple success | `OK` |
| Error | `ERROR:<code>`. See [Error codes](https://luxafor.com/help/developers/busy-tag-at-commands-firmware-3-0/#error-codes). |
| Prompt | `>`. The device is waiting for a data payload (file or pattern body). |
| Event | `+evn:<type>[,<data>]`. An asynchronous notification. See [Read events](https://luxafor.com/help/developers/busy-tag-at-commands-firmware-3-0/#read-events). |
| Log | `+log:<text>`. A diagnostic log line, for information only. |

## Read device information

| Command | Reply | What it does |
| --- | --- | --- |
| `AT+GDN` | `+DN:<name>` | Get the device name |
| `AT+GMN` | `+MN:<name>` | Get the manufacturer name (`SIA BUSY TAG`) |
| `AT+GID` | `+ID:<id>` | Get the unique device ID |
| `AT+GFV` | `+FV:<version>` | Get the firmware version (`3.0`) |
| `AT+GHV` | `+HV:<version>` | Get the hardware version (`2.0`) |
| `AT+GESPV` | `+ESPV:<version>` | Get the ESP-IDF version |
| `AT+GESPCT` | `+ESPCT:<date> <time>` | Get the firmware compile date and time |
| `AT+GTEMP` | `+TEMP:<celsius>` | Get the internal die temperature |
| `AT+GCHI` | `+CHI:<model>,<rev>,<cores>,<features>` | Get chip info |
| `AT+GUSBS` | `+USBS:<source>,<dtr>,<rts>` | Get the USB source and line state |
| `AT+GBLV` | `+BLV:<version>` | Get the bootloader version |
| `AT+GBLCD` | `+BLCD:<date> <time>` | Get the bootloader compile date and time |
| `AT+GBLIDF` | `+BLIDF:<version>` | Get the bootloader ESP-IDF version |

```
> AT+GDN
+DN:busytag-5F83C0
OK

> AT+GFV
+FV:3.0
OK

> AT+GHV
+HV:2.0
OK
```

```
> AT+GTEMP
+TEMP:42.5
OK

> AT+GCHI
+CHI:ESP32-S3,0,2,WiFi,BT,BLE,ExtPSRAM
OK

> AT+GUSBS
+USBS:HOST_APP,1,1
OK
```

- `AT+GCHI` `<features>` is a comma list drawn from `WiFi`, `BT`, `BLE`, `EmbFlash`, `EmbPSRAM`, `ExtPSRAM`. It reports chip silicon capabilities, not enabled firmware features.
- `AT+GUSBS` `<source>` is one of `POWER` (power-only supply), `HOST` (data host, port closed), `HOST_APP` (host with the serial port open), or `SUSPENDED`. `<dtr>`/`<rts>` are the current line states (`0`/`1`).

## Control the LED bar

The front RGB LED bar has 7 addressable positions. You select them with a 7-bit bitmask (0–127). `127` (binary `1111111`) selects all LEDs. Give colors as `RRGGBB` hex.

#### Set a solid color

| Command | What it does |
| --- | --- |
| `AT+SC=<pins>,<RRGGBB>` | Set a solid color on the selected LEDs |
| `AT+SC?` | Get the current solid color: `+SC:<pins>,<RRGGBB>` |

```
> AT+SC=127,FF0000      # all LEDs red
OK

# The pins value is a 7-bit mask, one bit per LED (LED1=1, LED2=2, LED3=4, ...).
> AT+SC=7,00FF00        # first three LEDs (1+2+4) green
OK

> AT+SC?
+SC:127,FF0000
OK
```

#### Make a custom pattern

A custom pattern is a list of steps. Each step has this form: `<pins>,<RRGGBB>,<speed>,<delay>`. `speed` and `delay` are in milliseconds. If you set bit 7 of `<pins>` (add 128), the step turns off the LEDs that were lit before it.

| Command | What it does |
| --- | --- |
| `AT+CP=<count>` | Set a pattern. The device replies `>` and then expects `<count>` step lines. |
| `AT+CPD=<lines>` | Set a pattern directly in one line (no `>` prompt) |
| `AT+CP?` | Get the current pattern (one `+CP:` line per step) |
| `AT+PP=<play>,<repeat>` | Play or stop the pattern. `repeat=255` means infinite. |
| `AT+PP?` | Get the play state: `+PP:<playing>,<repeat_count>` |

```
# Define a 2-step pattern (red, then green), each 100 ms with 500 ms hold
> AT+CP=2
>
+CP:127,FF0000,100,500
+CP:127,00FF00,100,500

OK

# Same 2-step pattern set in a single line.
# Steps use the +CP: prefix and are separated by a literal rn.
> AT+CPD=+CP:127,FF0000,100,500rn+CP:127,00FF00,100,500
OK

> AT+PP=1,3             # play 3 times
OK
> AT+PP=1,255           # play forever
OK
> AT+PP=0,0             # stop
OK
```

#### Play a built-in pattern

Firmware 3.0 has 25 built-in LED animations. You select them by ID.

| Command | What it does |
| --- | --- |
| `AT+GDPL` | List the built-in patterns: `+DPL:<id>,<name>` per line |
| `AT+DP=<id>` | Turn on a built-in pattern by ID (0–24) |

| ID | Name | ID | Name |
| --- | --- | --- | --- |
| 0 | Purple Glow | 13 | Yellow Running |
| 1 | Police 1 | 14 | Magenta Running |
| 2 | Police 2 | 15 | Cyan Running |
| 3 | Red Flashes | 16 | White Running |
| 4 | Green Flashes | 17 | Red Pulses |
| 5 | Blue Flashes | 18 | Green Pulses |
| 6 | Yellow Flashes | 19 | Blue Pulses |
| 7 | Magenta Flashes | 20 | Yellow Pulses |
| 8 | Cyan Flashes | 21 | Magenta Pulses |
| 9 | White Flashes | 22 | Cyan Pulses |
| 10 | Red Running | 23 | White Pulses |
| 11 | Green Running | 24 | Rainbow |
| 12 | Blue Running |   |   |

```
> AT+GDPL
+DPL:0,Purple Glow
+DPL:1,Police 1
...
+DPL:24,Rainbow
OK

> AT+DP=1               # activate "Police 1"
OK
> AT+PP=1,255           # play it forever
OK
```

## Control the screen

#### Set the brightness

```
> AT+DB?
+DB:75
OK
> AT+DB=50              # set display brightness to 50%
OK
```

#### Dim the backlight when idle

The LCD backlight can dim by itself after a period of inactivity. Both settings stay after a restart. Dimming is off by default.

| Command | What it does |
| --- | --- |
| `AT+DD=<0|1>` | Turn idle auto-dim on or off |
| `AT+DD?` | Get the state: `+DD:<0|1>` |
| `AT+DDC=<timeout_s>,<dim_level>` | Configure: timeout 1–120 s, dim level 0–20 (PWM duty) |
| `AT+DDC?` | Get the configuration: `+DDC:<timeout_s>,<dim_level>` |

```
> AT+DD=1               # enable idle dimming
OK
> AT+DDC=30,5           # dim to level 5 after 30 s idle
OK
> AT+DDC?
+DDC:30,5
OK
```

#### Show an image or a color

The Busy Tag shows PNG and GIF files that are stored in its file system.

| Command | What it does |
| --- | --- |
| `AT+GPL` | List the picture files: `+PL:<name>,<size>` per line |
| `AT+SP=<file>` | Show the named image. Emits `+evn:SP,<file>` |
| `AT+SP?` | Get the image that is shown now: `+SP:<file>` |
| `AT+DC=<RRGGBB>` | Fill the screen with a solid color |
| `AT+DC?` | Get the current fill color: `+DC:<RRGGBB>` |

```
> AT+GPL
+PL:logo.png,2048
+PL:animation.gif,8192
OK

> AT+SP=animation.gif
OK
+evn:SP,animation.gif

> AT+DC=FF8000          # fill the screen with orange
OK

> AT+DC?
+DC:FF8000
OK
```

#### Show or hide on-screen messages

The Busy Tag can print information messages (transfer progress, Wi-Fi state, errors) on the LCD. The setting stays after a restart.

```
> AT+SM?
+SM:1
OK
> AT+SM=0               # hide on-screen status messages
OK
```

#### Set up the toolbar

A toolbar at the top of the display can show a Wi-Fi indicator, the internal temperature, and a clock. You can turn on each item on its own and place it on the left or right side. All toolbar settings stay after a restart.

| Command | What it does |
| --- | --- |
| `AT+TB=<0|1>` | Show or hide the toolbar |
| `AT+TB?` | Get the toolbar state: `+TB:<0|1>` |
| `AT+TBI=<id>,<enabled>,<side>` | Configure one item: `id` 0=Wi-Fi, 1=temperature, 2=clock; `side` 0=left, 1=right |
| `AT+TBI?` | Get the item layout: `+TBI:<id>,<enabled>,<side>` per line |
| `AT+TBR=<0|1>` | Show or hide the numeric RSSI value next to the Wi-Fi icon |
| `AT+TBR?` | Get the RSSI display state: `+TBR:<0|1>` |
| `AT+BO=<0-100>` | Set the bar opacity (applies to the toolbar scrim and the status bar) |
| `AT+BO?` | Get the bar opacity: `+BO:<0-100>` |

```
> AT+TB=1               # show the toolbar
OK
> AT+TBI=2,1,1          # clock enabled, right side
OK
> AT+TBI?
+TBI:0,1,0
+TBI:1,0,0
+TBI:2,1,1
OK
> AT+BO=60              # 60% bar opacity
OK
> AT+TBR=1              # show RSSI next to the Wi-Fi icon
OK
```

#### Show the setup QR code

The Busy Tag can show a setup QR code on the display. The QR code holds a deep-link URL (see `AT+SDLU`). The mobile app uses it to set up the device.

```
> AT+QR=1               # show the setup QR code
OK
> AT+QR?
+QR:1
OK
> AT+QR=0               # hide it again
OK
```

## Set the time zone and power save

#### Set the time zone

The clock (toolbar item 2) uses NTP time when Wi-Fi is connected. The configured POSIX timezone string adjusts it. The setting stays after a restart.

```
> AT+TZ?
+TZ:CET-1CEST,M3.5.0,M10.5.0/3
OK
> AT+TZ=EST5EDT         # set US Eastern time
OK
```

#### Turn power save on or off

Power-save mode turns on dynamic CPU frequency scaling, Wi-Fi modem sleep and adaptive transmit power. It lowers heat and power use. The cost is a small increase in Wi-Fi latency. The setting stays after a restart.

```
> AT+PS?
+PS:1
OK
> AT+PS=0               # disable power save
OK
```

## Set up Wi-Fi

#### Choose the Wi-Fi mode

| Command | What it does |
| --- | --- |
| `AT+WM=<mode>` | Set the Wi-Fi mode: 0=OFF, 1=station, 2=access point, 3=STA+AP. The setting stays after a restart. |
| `AT+WM?` | Get the Wi-Fi mode: `+WM:<mode>` |

In AP and STA+AP modes, the local HTTP server (see [Use the local HTTP server](https://luxafor.com/help/developers/busy-tag-at-commands-firmware-3-0/#use-the-local-http-server)) starts by itself. It runs without authentication, because the AP network is private. In STA-only mode, the server is stopped.

```
> AT+WM=1               # station mode
OK
> AT+WM?
+WM:1
OK
```

#### Connect to a Wi-Fi network

| Command | What it does |
| --- | --- |
| `AT+STA=<ssid>,<password>` | Connect to an access point |
| `AT+STA?` | Get the status: `+STA:<connected>,<ssid>,<ip>,<rssi>` |
| `AT+DSTA` | Disconnect from the access point |
| `AT+GIP` | Get the IP address: `+IP:<ip>` (`0.0.0.0` when not connected) |

```
> AT+STA=MyNetwork,MyPassword
OK
+evn:WIFI_CONNECTED,MyNetwork,192.168.1.42

> AT+STA?
+STA:1,MyNetwork,192.168.1.42,-58
OK

> AT+GIP
+IP:192.168.1.42
OK

> AT+DSTA
OK
```

If the connection fails, the device sends `+evn:WIFI_CONNECT_FAILED,<ssid>,<reason>`. `<reason>` is the ESP-IDF disconnect reason code.

#### Scan for Wi-Fi networks

Scanning is asynchronous. `AT+WSCAN=` starts a scan. `AT+WSCAN?` gets the results.

| Command | What it does |
| --- | --- |
| `AT+WSCAN=[ssid],[auth]` | Start a scan. Both filters are optional. `ssid` is a case-insensitive substring match. `auth` filters by security type (e.g. `OPEN`, `WPA2`, `WPA3`). |
| `AT+WSCAN?` | Get the results: `+WSCAN:<count>`, then one `+WSCAN:<ssid>,<channel>,<rssi>,<auth>` line per network. `+WSCAN:BUSY` while a scan is running. |

```
> AT+WSCAN=             # scan everything
OK

> AT+WSCAN?
+WSCAN:2
+WSCAN:MyNetwork,6,-58,WPA2
+WSCAN:CoffeeShop,11,-73,OPEN
OK
```

Auth strings: `OPEN`, `WEP`, `WPA`, `WPA2`, `WPA/WPA2`, `WPA3`, `WPA2/WPA3`, `WPA-ENT`, `WPA2-ENT`, `WPA3-ENT`, `WAPI`, `OWE`.

#### Start an access point

The `<auth>` parameter is a numeric ESP-IDF auth mode (0=open, 2=WPA-PSK, 3=WPA2-PSK, 4=WPA/WPA2-PSK, 6=WPA3-PSK).

| Command | What it does |
| --- | --- |
| `AT+AP=<ssid>,<password>[,<channel>][,<max_conn>][,<auth>]` | Configure and start the access point. Defaults: channel 6, max connections 4, auth WPA2-PSK. Switches the device into AP mode if needed. |
| `AT+AP?` | Get the AP status: `+AP:<ssid>,<connected_stations>` or `+AP:DISABLED` |
| `AT+APST?` | List the connected stations: `+APST:<count>`, then `+APST:<mac>,<ip>,<rssi>` per station |
| `AT+APKICK=<mac>` | Disconnect a station from the AP |

```
> AT+AP=BusyTag-Setup,setup1234
OK

> AT+AP?
+AP:BusyTag-Setup,1
OK

> AT+APST?
+APST:1
+APST:A4:C1:38:12:34:56,192.168.4.2,-40
OK

> AT+APKICK=A4:C1:38:12:34:56
OK
```

## Use the cloud connection

When the Busy Tag is connected as a Wi-Fi station, it keeps a WebSocket connection to the Busy Tag cloud. The cloud can send the same AT commands remotely. The device signs in with an Ed25519 key pair that it creates on the first boot.

#### Check the WebSocket and set URLs

| Command | What it does |
| --- | --- |
| `AT+WS?` | Get the WebSocket status: `+WS:<state>,<url>` |
| `AT+WS=<url>` | Set the WebSocket URL (`wss://...`). Takes effect on the next restart. |
| `AT+WSREG?` | Get the registration URL: `+WSREG:<url>` |
| `AT+WSREG=<url>` | Set the registration URL (`https://...`). Used on the next registration. |
| `AT+SDLU?` | Get the setup deep-link URL base: `+SDLU:<url>` |
| `AT+SDLU=<url>` | Set the deep-link URL base that the setup QR code uses |
| `AT+GCAK` | Get the Ed25519 public key of the device: `+CAK:<hex>` |

WebSocket states: `0`=disconnected, `1`=connecting, `2`=TLS handshake, `3`=authenticating, `4`=subscribed (fully online), `5`=error.

```
> AT+WS?
+WS:4,wss://iot.busytag.com/ws
OK

> AT+GCAK
+CAK:3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29
OK
```

#### Download and upload files over the network

| Command | What it does |
| --- | --- |
| `AT+DL=<url>,<filename>[,<size>]` | Download a file over HTTP(S) into storage. A `.bin` filename starts an OTA firmware update. The optional `<size>` (bytes) gives percentage progress when the server sends no `Content-Length`. |
| `AT+UL=<url>,<filename>` | Upload a stored file to the cloud with an HTTPS POST. The device streams `/data/<filename>` and sends its SHA-256 for server-side verification. |
| `AT+DPR=<0|1>` | Turn transfer progress events on or off |
| `AT+DPR?` | Get the progress reporting state: `+DPR:<0|1>` |

```
> AT+DPR=1
OK

> AT+DL=http://example.com/pic.png,pic.png
+evn:DL,pic.png,51200,204800,25,180.5,8
+evn:DL,pic.png,204800,204800,100,195.2,0
+DL:OK,pic.png
OK

# Firmware OTA: download a .bin, update runs after the transfer
> AT+DL=http://example.com/fw.bin,fw.bin
+evn:FWDL,STARTING
...
+evn:FWDL,DOWNLOADED
+evn:FU,42.00%
...
+DL:OK,fw.bin,UPDATE_PENDING
OK

> AT+UL=https://iot.busytag.com/upload,logo.png
+evn:UL,logo.png,102400,102400,100,150.0,0
+UL:OK,logo.png
OK
```

Progress events have this form: `+evn:DL,<file>,<current>,<total>,<percent>,<kB/s>,<eta_s>` (`UL` for uploads). The device sends at most one every 5 % or 500 ms.

#### Use the local HTTP server

The device runs a local HTTP server. It gives access to the AT command set over REST. The mobile apps use it when they are connected to the AP of the device.

| Command | What it does |
| --- | --- |
| `AT+LS=<enable>,<port>,<auth_token>` | Configure the server. Port 1024–65535. A non-empty token turns on authentication. |
| `AT+LS?` | Get the status: `+LS:<enabled>,<port>,<auth_required>,<RUNNING|STOPPED>` |
| `AT+LT?` | Get the current auth token: `+LT:<token>` |
| `AT+LT` | Make a new auth token: `+LT:<new_token>` |

```
> AT+LS?
+LS:1,8080,1,RUNNING
OK

> AT+LT?
+LT:a1b2c3d4e5f6
OK

> AT+LT                 # rotate the token
+LT:f6e5d4c3b2a1
OK
```

## Manage files

#### Check the free space

```
> AT+GFSS               # free storage, bytes
+FSS:1048576
OK
> AT+GTSS               # total storage, bytes
+TSS:3145728
OK
```

#### List, upload, download and delete files

| Command | What it does |
| --- | --- |
| `AT+GFL` | List all files: `+FL:<name>,<type>,<size>` per line |
| `AT+UF=<file>,<size>` | Upload a file over USB. The device replies `>` and then expects `<size>` bytes. |
| `AT+GF=<file>` | Download a file from the device: `+GF:<file>,<size>`, then the raw bytes |
| `AT+DF=<file>` | Delete a file |
| `AT+AFSS` | Scan the file storage again |

```
> AT+GFL
+FL:config.json,json,256
+FL:def.png,png,1024
OK

# Upload a 12-byte file
> AT+UF=test.txt,12
>
Hello World!
OK

# Read a file back
> AT+GF=config.json
+GF:config.json,256
{ ...file content... }

> AT+DF=old_file.txt
OK
```

After the `>` prompt, the device waits up to 10 seconds for the full payload. If the byte count is not reached in time, the transfer stops with a timeout error.

## Restart, format or reset the Busy Tag

**Warning:** `AT+FD` erases all stored files. `AT+FR` also erases every saved setting (Wi-Fi credentials, cloud registration, display and LED configuration) and restarts the device in its factory state. Use with caution.

| Command | What it does |
| --- | --- |
| `AT+GLEC` | Get the last error code: `+LEC:<code>` |
| `AT+GLRR0` | Get the last reset reason for core 0 |
| `AT+GLRR1` | Get the last reset reason for core 1 |
| `AT+RST` | Restart the device |
| `AT+FD` | Format storage |
| `AT+FR` | Factory reset: format storage, erase all settings (NVS), restart |

#### Reset reason codes

`AT+GLRR0` and `AT+GLRR1` return the last reset reason for CPU core 0 and core 1 as a numeric code (`+LRR0:<code>` / `+LRR1:<code>`).

| Code | Meaning |
| --- | --- |
| 0 | No reset reason recorded |
| 1 | Power-on reset (Vbat) |
| 3 | Software reset of the digital core |
| 5 | Deep-sleep wake reset |
| 7 | Timer Group 0 watchdog reset (core) |
| 8 | Timer Group 1 watchdog reset (core) |
| 9 | RTC watchdog reset (core) |
| 10 | Intrusion-detection reset |
| 11 | Timer Group 0 watchdog reset (CPU) |
| 12 | Software reset of the CPU |
| 13 | RTC watchdog reset (CPU) |
| 15 | Brownout reset (unstable VDD) |
| 16 | RTC watchdog reset (core + RTC) |
| 17 | Timer Group 1 watchdog reset (CPU) |
| 18 | Super watchdog reset |
| 19 | Clock-glitch reset |
| 20 | eFuse CRC reset |
| 21 | USB UART reset |
| 22 | USB JTAG reset |
| 23 | Power-glitch reset |

## Read events

The device sends unsolicited `+evn:` lines on the serial port. They can arrive at any time, including between a command and its `OK`.

| Event | Meaning |
| --- | --- |
| `+evn:SP,<file>` | An image was shown on the display |
| `+evn:WIFI_CONNECTED,<ssid>,<ip>` | The station connected and got an IP address |
| `+evn:WIFI_CONNECT_FAILED,<ssid>,<reason>` | The station connection failed (ESP-IDF reason code) |
| `+evn:DL,<file>,<cur>,<total>,<pct>,<kBps>,<eta>` | Download progress (when `AT+DPR=1`) |
| `+evn:UL,<file>,<cur>,<total>,<pct>,<kBps>,<eta>` | Upload progress (when `AT+DPR=1`) |
| `+evn:DL_START,<file>` | A download started by the cloud has started |
| `+evn:DL_COMPLETE,<file>,<bytes>` | A download started by the cloud has finished |
| `+evn:DL_ERROR,<file>` | A download started by the cloud has failed |
| `+evn:UL_START,<file>` | The upload to the cloud has started |
| `+evn:UL_COMPLETE,<file>,<bytes>` | The upload to the cloud has finished |
| `+evn:UL_ERROR,<file>` | The upload to the cloud has failed |
| `+evn:FWDL,STARTING` | The firmware download is starting |
| `+evn:FWDL,DOWNLOADED` | The firmware image is downloaded and the update will run |
| `+evn:FWDL,FAILED` | The firmware download or update failed |
| `+evn:FU,<percent>%` | Firmware update flash progress |

Diagnostic log lines start with `+log:`. Your host software can ignore them.

## Error codes

When a command fails, the device replies `ERROR:<code>`. You can also get the last error with `AT+GLEC`.

| Code | Meaning |
| --- | --- |
| -1 | None |
| 0 | Unknown error |
| 1 | Unknown command |
| 2 | Invalid argument |
| 3 | File not found |
| 4 | Invalid size |
| 5 | Storage not mounted |
| 6 | File list error |
| 7 | Storage info error |
| 8 | Memory allocation error |
| 9 | Wi-Fi scan error |
| 10 | Token error |
| 11 | Sensor error |
| 12 | File delete error |
| 13 | File reception timeout |

**Changed from firmware 2.0:** Codes 9 (Wi-Fi scan error) and 10 (token error) are new in 3.0. The sensor, file-delete and timeout codes moved from 11, 12 and 13 in 2.0 to match.

## All commands at a glance

| Command | Type | Description |
| --- | --- | --- |
| `AT` | Action | Test connection |
| `AT+GDN` | Get | Device name |
| `AT+GMN` | Get | Manufacturer name |
| `AT+GID` | Get | Device ID |
| `AT+GFV` | Get | Firmware version |
| `AT+GHV` | Get | Hardware version |
| `AT+GESPV` | Get | ESP-IDF version |
| `AT+GESPCT` | Get | Compile date/time |
| `AT+GTEMP` | Get | Internal temperature |
| `AT+GCHI` | Get | Chip info |
| `AT+GUSBS` | Get | USB source and line state |
| `AT+GBLV` | Get | Bootloader version |
| `AT+GBLCD` | Get | Bootloader compile date |
| `AT+GBLIDF` | Get | Bootloader ESP-IDF version |
| `AT+GLEC` | Get | Last error code |
| `AT+GLRR0` | Get | Last reset reason, core 0 |
| `AT+GLRR1` | Get | Last reset reason, core 1 |
| `AT+SC?/=` | Get/Set | Solid LED color |
| `AT+CP?/=` | Get/Set | Custom pattern |
| `AT+CPD=` | Set | Custom pattern (direct) |
| `AT+PP?/=` | Get/Set | Play pattern |
| `AT+GDPL` | Get | Built-in pattern list |
| `AT+DP=` | Set | Activate built-in pattern by ID |
| `AT+DB?/=` | Get/Set | Display brightness |
| `AT+DD?/=` | Get/Set | Idle backlight dimming |
| `AT+DDC?/=` | Get/Set | Idle dimming config |
| `AT+SP?/=` | Get/Set | Show picture |
| `AT+DC?/=` | Get/Set | Display solid color fill |
| `AT+SM?/=` | Get/Set | On-screen status messages |
| `AT+TB?/=` | Get/Set | Status toolbar |
| `AT+TBI?/=` | Get/Set | Toolbar item layout |
| `AT+TBR?/=` | Get/Set | Toolbar Wi-Fi RSSI display |
| `AT+BO?/=` | Get/Set | Bar opacity |
| `AT+QR?/=` | Get/Set | Setup QR code |
| `AT+GPL` | Get | Picture list |
| `AT+TZ?/=` | Get/Set | Timezone (POSIX TZ) |
| `AT+PS?/=` | Get/Set | Power save |
| `AT+WM?/=` | Get/Set | Wi-Fi mode |
| `AT+STA?/=` | Get/Set | Station status / connect |
| `AT+DSTA` | Action | Disconnect station |
| `AT+GIP` | Get | IP address |
| `AT+WSCAN?/=` | Get/Set | Wi-Fi scan |
| `AT+AP?/=` | Get/Set | Access point |
| `AT+APST?` | Get | AP connected stations |
| `AT+APKICK=` | Action | Kick station from AP |
| `AT+WS?/=` | Get/Set | Cloud WebSocket status / URL |
| `AT+WSREG?/=` | Get/Set | Registration URL |
| `AT+SDLU?/=` | Get/Set | Setup deep-link URL base |
| `AT+GCAK` | Get | Cloud auth public key (Ed25519) |
| `AT+DL=` | Action | Download file from URL (OTA for .bin) |
| `AT+UL=` | Action | Upload stored file to cloud |
| `AT+DPR?/=` | Get/Set | Transfer progress reporting |
| `AT+LS?/=` | Get/Set | Local HTTP server |
| `AT+LT?` | Get | Local server auth token |
| `AT+LT` | Action | Regenerate auth token |
| `AT+GFL` | Get | File list |
| `AT+GFSS` | Get | Free storage size |
| `AT+GTSS` | Get | Total storage size |
| `AT+UF=` | Action | Upload file (USB) |
| `AT+GF=` | Action | Get/download file (USB) |
| `AT+DF=` | Action | Delete file |
| `AT+AFSS` | Action | Re-scan storage |
| `AT+RST` | Action | Restart |
| `AT+FD` | Action | Format disk |
| `AT+FR` | Action | Factory reset |

## Code examples

All examples open the USB CDC serial port at `460800` baud, send each command ending with `rn`, and read the `+.../OK` reply line. Your host software must handle unsolicited `+evn:` and `+log:` lines between replies.

The serial port name depends on your operating system. On Windows it is a COM port (e.g. `COM3`). On macOS it is a `/dev/tty.usbmodem*` device. On Linux it is a `/dev/ttyACM*` device. Use the value that matches your computer.

#### Python

```
import serial

ser = serial.Serial('COM3', 460800, timeout=1)

def cmd(c):
    ser.write((c + "rn").encode())
    while True:
        line = ser.readline().decode().strip()
        # Skip asynchronous event/log lines
        if line.startswith("+evn:") or line.startswith("+log:"):
            continue
        return line

print(cmd("AT"))                          # OK
print(cmd("AT+GFV"))                      # +FV:3.0
cmd("AT+SC=127,0000FF")                   # all LEDs blue
cmd("AT+STA=MyNetwork,MyPassword")        # join Wi-Fi
cmd("AT+DL=http://example.com/pic.png,pic.png")
cmd("AT+SP=pic.png")                      # show the downloaded image

ser.close()
```

#### C#

```
using System;
using System.IO.Ports;

var port = new SerialPort("COM3", 460800) { NewLine = "rn", ReadTimeout = 1000 };
port.Open();

string Cmd(string c)
{
    port.WriteLine(c);
    while (true)
    {
        var line = port.ReadLine().Trim();
        if (line.StartsWith("+evn:") || line.StartsWith("+log:"))
            continue;   // skip asynchronous lines
        return line;
    }
}

Console.WriteLine(Cmd("AT"));         // OK
Console.WriteLine(Cmd("AT+GFV"));     // +FV:3.0
Cmd("AT+SC=127,0000FF");              // all LEDs blue
Cmd("AT+STA=MyNetwork,MyPassword");   // join Wi-Fi
Cmd("AT+SP=logo.png");                // show an image

port.Close();
```

#### Swift

This example uses the `ORSSerialPort` library (macOS). The library delivers replies to the delegate of the port. The example shows only the writes.

```
import ORSSerial

let port = ORSSerialPort(path: "/dev/tty.usbmodem1101")!
port.baudRate = 460800
port.open()

func cmd(_ c: String) {
    port.send((c + "rn").data(using: .utf8)!)
}

cmd("AT")                                  // OK
cmd("AT+GFV")                              // +FV:3.0
cmd("AT+SC=127,0000FF")                    // all LEDs blue
cmd("AT+STA=MyNetwork,MyPassword")         // join Wi-Fi
cmd("AT+SP=logo.png")                      // show an image

port.close()
```

## Still need help?

[Send us a message](https://luxafor.com/help/contact/) and tell us:

- which device you have and where you bought it
- what you see, and what you expected to see
- which steps on this page you have already tried
- your operating system and Luxafor app version, if it is a software problem
- your order number, if you have one

A short video or photo of the problem helps us fix it faster. If the problem is with the connection, film the device at the moment it tries to connect.
