Use the local API

Before you start

• Check your model and firmware

  Use a compatible LANBON edition. Note the model and firmware version in panel settings and connect your computer or controller to the same trusted local network. For a Mesh installation, use the root panel’s address and token.

• Enable Open Integration on the panel

  On the panel, go to Settings → Open Integration and enable the master switch. Select Show Token to read the current token. Note the panel’s local IP and API port, which defaults to 8765. Clients with mDNS can look for _lanbon._tcp.local. Send the token in the Authorization header.

Read devices and capabilities

1. Verify the connection

   Run this in Bash, or Git Bash on Windows. Enter your panel’s address, scheme, port and token. Put IPv6 addresses in brackets. A successful /info call returns HTTP 200. Note gateway_id, firmware_version and transports.events. The scheme defaults to HTTP. Enter https when advertised by your device.

   Copy

   read -r -p 'Panel IP or hostname: ' LOIP_HOST
   read -r -p 'API scheme [http]: ' LOIP_SCHEME
   if [ -z "$LOIP_SCHEME" ]; then LOIP_SCHEME=http; fi
   read -r -p 'API port [8765]: ' LOIP_PORT
   if [ -z "$LOIP_PORT" ]; then LOIP_PORT=8765; fi
   LOIP_BASE="$LOIP_SCHEME://$LOIP_HOST:$LOIP_PORT"
   read -r -s -p 'Panel token: ' LOIP_TOKEN
   echo
   curl --noproxy "*" --max-time 10 -sS -i -H "Authorization: Bearer $LOIP_TOKEN" "$LOIP_BASE/api/v1/info"

2. Read the snapshot

   Run the next command in the same terminal. Find the online target by devices[].id, then copy its component id from components[]. Check enabled, commands and constraints. The response describes the actual mode, supported commands and valid ranges.

   Copy

   curl --noproxy "*" --max-time 10 -sS -i -H "Authorization: Bearer $LOIP_TOKEN" "$LOIP_BASE/api/v1/devices"

Send a command and verify

1. Prepare the request

   Choose a function you can operate safely. Save this example as loip-command.json, replace both IDs, and set command and params according to the component’s commands and constraints. Give each new operation a fresh request_id.

   Copy

   {
     "request_id": "setup-001",
     "device_id": "aabbccddeeff",
     "component_id": "switch:1",
     "command": "set_on",
     "params": {
       "on": true
     }
   }

2. Submit and read back

   HTTP 200 with completed means the command finished. HTTP 202 with accepted means the command was received. Run the snapshot command again and check the target component’s state. The example switch should show on as true. After a timeout, read the state before deciding whether to send another command.

   Copy

   curl --noproxy "*" --max-time 10 -sS -i -H "Authorization: Bearer $LOIP_TOKEN" -H "Content-Type: application/json" --data-binary @loip-command.json "$LOIP_BASE/api/v1/command"

Common component commands

These are LOIP command examples. Check the component type, commands and allowed values in the device snapshot, then use the matching command and parameters in the full JSON above. Features such as curtain control and dimming vary by model and mode.

Switch switch

set_on {"on":true}

Dimmer light

set_brightness {"brightness":50}

Fan fan

set_speed_level {"speed_level":1}

Curtain cover

stop {}

Water heater water_heater

set_on {"on":true}

Keep state in sync

• WebSocket

  If /info reports events as websocket, connect to ws://<panel-address>:<port>/api/v1/events (wss for HTTPS) with the same Authorization header in the handshake. Refresh /devices on initial connection, reconnection, parse errors or topology_changed. A state_changed event supplies the current state for the affected component.

• Polling

  If /info reports events as polling, read /devices periodically, for example every 30 seconds, and refresh after sending a command. When the device returns an ETag, reuse it verbatim in If-None-Match. Keep the previous snapshot on 304. Treat revision as an opaque identifier.

Troubleshoot and disable

• Panel not found or connection times out

  Check the master switch, root panel address and configured port. If network isolation blocks discovery, enter the panel IP manually. Keep the API on your trusted local network.

• 401, target not found or invalid parameters

  For 401, read the current token from the panel. If a component is missing, a device is offline or parameters are invalid, refresh the snapshot and check availability, IDs, the current mode and allowed parameters.

• End access

  Turn off Open Integration on the panel to stop access. To invalidate old credentials, rotate or revoke the token on the panel and update clients that should keep access. Run unset LOIP_TOKEN to clear the variable from this terminal session.

Resources and downloads

python -m pip install aiolanbon==0.2.1