client
Small HTTP client for Twinkly devices.
AUTH_HEADER = 'X-Auth-Token'
module-attribute
¶
TWINKLY_API_PREFIX = '/xled/v1'
module-attribute
¶
TwinklyResponse
dataclass
¶
Successful HTTP response and its decoded JSON object.
Source code in tinkly/client.py
AuthToken
dataclass
¶
Authentication token, verification response, and optional expiry time.
Source code in tinkly/client.py
value: str = field(repr=False)
class-attribute
instance-attribute
¶
Base64 token used in HTTP headers and decoded for realtime UDP packets.
challenge_response: str = field(repr=False)
class-attribute
instance-attribute
¶
Challenge response returned by login and sent back during verification.
expires_at: float | None
instance-attribute
¶
Expiry as Unix time in seconds, or None if the device supplied no expiry.
expired: bool
property
¶
Whether the known expiry time has passed; False if no expiry is known.
TwinklyClient
dataclass
¶
Synchronous HTTP client for a single Twinkly device.
Each endpoint property read sends a fresh GET request and returns a TwinklyResponse containing http_status and data. Properties marked writable accept a dict[str, object] JSON body and POST assignments; assignment discards the response, so use post() when it is needed. Other properties are read-only. Authentication is required and obtained automatically unless stated otherwise. Request errors propagate to the caller.
Each request opens and closes an HTTP connection; retries, realtime frame pacing, and reconnection belong to the caller. Serialize all use of a client; instances are not thread-safe.
Source code in tinkly/client.py
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 | |
host: str
instance-attribute
¶
Device hostname or IPv4 address; HTTP requests use port 80.
mac: str | None = None
class-attribute
instance-attribute
¶
Optional MAC address used to check the login challenge response.
timeout: float = 5.0
class-attribute
instance-attribute
¶
HTTP connection and socket operation timeout in seconds.
token: AuthToken | None = field(default=None, init=False)
class-attribute
instance-attribute
¶
Current authentication token, obtained automatically when needed.
current_movie: TwinklyResponse
property
¶
Read the device's current movie selection.
GET led/movies/current.
current_music_driver_set: TwinklyResponse
property
¶
Read the currently selected music driver set.
GET music/drivers/sets/current.
current_playlist_entry: TwinklyResponse
property
¶
Read the current entry in the device playlist.
GET playlist/current.
device_name: TwinklyResponse
property
¶
Read the device's configured name.
GET device_name.
effects: TwinklyResponse
property
¶
Read the effects available on the device.
GET led/effects.
firmware_version: TwinklyResponse
property
¶
Read the firmware version without logging in.
GET fw/version. Authentication is not required.
mic_config: TwinklyResponse
property
¶
Read the device's microphone configuration.
GET mic/config.
mic_sample: TwinklyResponse
property
¶
Read a microphone sample reported by the device.
GET mic/sample.
movie_config: TwinklyResponse
property
¶
Read the device's movie playback configuration.
GET led/movie/config.
movies: TwinklyResponse
property
¶
Read the device's stored movie listing.
GET movies.
mqtt_config: TwinklyResponse
property
¶
Read the device's MQTT configuration.
GET mqtt/config.
music_driver_sets: TwinklyResponse
property
¶
Read the available music driver sets.
GET music/drivers/sets.
music_drivers: TwinklyResponse
property
¶
Read the music drivers available on the device.
GET music/drivers.
network_scan_results: TwinklyResponse
property
¶
Read Wi-Fi scan results after starting a scan with start_network_scan().
GET network/scan_results.
network_status: TwinklyResponse
property
¶
Read the device's current network status.
GET network/status.
playlist: TwinklyResponse
property
¶
Read the device's configured playlist.
GET playlist.
status: TwinklyResponse
property
¶
Read device status without logging in.
GET status. Authentication is not required.
summary: TwinklyResponse
property
¶
Read the device summary supplied by the summary endpoint.
GET summary.
brightness: TwinklyResponse
property
writable
¶
Read or update output brightness using mode, type, and value fields.
GET led/out/brightness, POST led/out/brightness.
current_effect: TwinklyResponse
property
writable
¶
Read the selected effect or select one by assigning an effect_id body.
GET led/effects/current, POST led/effects/current.
layout_full: TwinklyResponse
property
writable
¶
Read or upload the full LED layout, including coordinates and source.
GET led/layout/full, POST led/layout/full.
led_color: TwinklyResponse
property
writable
¶
Read or update the static LED color using the device's color fields.
GET led/color, POST led/color.
led_config: TwinklyResponse
property
writable
¶
Read or update the device's LED string configuration.
GET led/config, POST led/config.
led_mode: TwinklyResponse
property
writable
¶
Read the operating mode or set it by assigning a body with a mode field.
GET led/mode, POST led/mode.
saturation: TwinklyResponse
property
writable
¶
Read or update output saturation using mode, type, and value fields.
GET led/out/saturation, POST led/out/saturation.
timer: TwinklyResponse
property
writable
¶
Read or update the device timer's time_now, time_on, and time_off fields.
GET timer, POST timer.
authenticate() -> AuthToken
¶
Log in with a random challenge, verify the issued token, and return it.
Store the token on this client and calculate its expiry when supplied by the device. Cache only a successfully verified, unexpired token. If mac is set, check the returned challenge response before verification. Invalid or non-positive expiry raises AuthenticationError; authentication and request failures propagate without retrying verification.
Source code in tinkly/client.py
get(path: str, authenticated: bool = True) -> TwinklyResponse
¶
GET an API-relative endpoint, optionally obtaining and sending a token.
post(path: str, body: dict[str, object], authenticated: bool = True) -> TwinklyResponse
¶
POST a JSON object to an API-relative endpoint and return its response.
Authentication is enabled by default; login uses authenticated=False.
Source code in tinkly/client.py
post_bytes(path: str, payload: bytes, content_type: str, authenticated: bool = True) -> TwinklyResponse
¶
POST raw bytes with the supplied Content-Type and return the response.
The path is relative to /xled/v1/. Content-Length is calculated from
payload. Authentication is enabled unless explicitly disabled.
Source code in tinkly/client.py
delete(path: str) -> TwinklyResponse
¶
echo(body: dict[str, object]) -> TwinklyResponse
¶
delete_layout_full() -> TwinklyResponse
¶
start_network_scan() -> TwinklyResponse
¶
Start a Wi-Fi network scan and return the device's acknowledgement.
Read network_scan_results separately once the scan has completed. This method does not wait or poll for completion.
Source code in tinkly/client.py
set_realtime_mode() -> TwinklyResponse
¶
set_off_mode() -> TwinklyResponse
¶
request(method: str, path: str, body: dict[str, object] | None = None, payload: bytes | None = None, content_type: str = 'application/json', authenticated: bool = True) -> TwinklyResponse
¶
Send one HTTP request and validate the JSON object response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
HTTP method such as GET, POST, or DELETE. |
required |
path
|
str
|
Endpoint relative to |
required |
body
|
dict[str, object] | None
|
Optional JSON object; cannot be combined with payload. |
None
|
payload
|
bytes | None
|
Optional raw request bytes. |
None
|
content_type
|
str
|
Content-Type header; defaults to application/json. |
'application/json'
|
authenticated
|
bool
|
Obtain a token if needed and send X-Auth-Token. |
True
|
Returns:
| Type | Description |
|---|---|
TwinklyResponse
|
HTTP status and decoded JSON data. An empty response body is |
TwinklyResponse
|
treated as an empty JSON object. |
Raises:
| Type | Description |
|---|---|
ValueError
|
Both body and payload were supplied. |
AuthenticationError
|
Authentication fails or HTTP 401 is returned. HTTP 401 also clears the stored token. |
UnsupportedEndpointError
|
The device returns HTTP 404. |
ProtocolError
|
Sending or reading raises OSError or HTTPException, another HTTP error is returned, the body is not a valid UTF-8 JSON object, or a supplied application code is not 1000. |
Source code in tinkly/client.py
getter(path: str, authenticated: bool = True) -> property
¶
Create a read-only endpoint property returning a fresh TwinklyResponse.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Endpoint relative to the device's |
required |
authenticated
|
bool
|
Obtain a token if needed and include it in each request. |
True
|
Reading the property performs an HTTP GET every time; results are not cached. Request errors propagate to the caller.
Source code in tinkly/client.py
setter(path: str) -> property
¶
Create a readable, writable authenticated endpoint property.
Reads perform HTTP GET and return a fresh TwinklyResponse. Assignments
accept a dict[str, object] JSON body and perform HTTP POST to the same
path, relative to /xled/v1/. Assignment discards the response; use
TwinklyClient.post when its result is needed. Request errors propagate.