{"id":44372713,"url":"https://github.com/andrasg/loxone-ts-api","last_synced_at":"2026-02-11T20:26:05.134Z","repository":{"id":312725746,"uuid":"1048257293","full_name":"andrasg/loxone-ts-api","owner":"andrasg","description":"A node module written in TypeScript to communicate with Loxone Miniservers via websockets.","archived":false,"fork":false,"pushed_at":"2025-09-27T06:53:40.000Z","size":204,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T08:54:46.884Z","etag":null,"topics":["loxone","typescript","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrasg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T07:06:58.000Z","updated_at":"2025-09-27T06:53:12.000Z","dependencies_parsed_at":"2025-09-01T17:28:14.063Z","dependency_job_id":"81696c24-a9d5-4d9b-83c2-cf6f741a9ce5","html_url":"https://github.com/andrasg/loxone-ts-api","commit_stats":null,"previous_names":["andrasg/loxone-ts-api"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/andrasg/loxone-ts-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrasg%2Floxone-ts-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrasg%2Floxone-ts-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrasg%2Floxone-ts-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrasg%2Floxone-ts-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrasg","download_url":"https://codeload.github.com/andrasg/loxone-ts-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrasg%2Floxone-ts-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29343828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T20:11:40.865Z","status":"ssl_error","status_checked_at":"2026-02-11T20:10:41.637Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["loxone","typescript","websocket"],"created_at":"2026-02-11T20:26:04.396Z","updated_at":"2026-02-11T20:26:05.127Z","avatar_url":"https://github.com/andrasg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# loxone-ts-api\nA Node module written in TypeScript for facilitating communication with Loxone Miniservers. Communication is done using http and WebSockets.\n\nCurrently only implemented http/ws communication to enable support for Gen.1 and Gen.2 Miniservers. https/wss communication currently not supported, but planned.\n\n## Key featrues\n\n- Connects to the Loxone Miniserver via WebSocket\n  - Support for both Gen.1 and Gen.2 Miniservers\n  - Support for token-based auth, token refresh and token invalidation\n  - Supports automatic reconnect\n  - Automatically maintains connection upon disconnect or error\n- Event emitting\n  - emits events on key connection events\n  - emits events for message received\n  - ability to filter events to specific UUIDs\n- Loxone structure file parsing\n  - Ability to read and parse structure file\n  - Provides rich TypeScript classes representing Loxone rooms, controls and states\n  - Supplies rich event context for each event (value or text update)\n- Control any Loxone control\n  - Supports websocket-based control of any Loxone control\n- Nerdy stuff\n  - Fully typed TypeScript objects, avoiding the `any` type\n  - Implemented with async/await - code waits for async websocket response message before returning\n  - This package is used as the foundation of `matterbridge-loxone`\n\n### Structure file parsing\n\nAfter calling `LoxoneClient.parseStructureFile()`, the client will read the `LoxAPP3.json` and parse all rooms, their available controls and states associated. These can be read on the client object through the `rooms`, `controls` and `states` collections.\nIt will also start enriching the received events with the associates `State` object that contains details about the state, its associated control and the room the control is in.\n\n### Watchlist\n\nBy default the client will emit all events received via websocket. You can add status UUIDs to the watchlist by calling `LoxoneClient.addUuidToWatchList(uuid)`. Upon adding items to the watchlist, the client will only log and emit events received for statuses associated with the watched UUIDs.\n\n### Error handling\n\nThe client tries to maintain the connection with the Miniserver even when network interruptions occur. Errors in command calls should not make the client crash.\n\n## Requirements\n\nRequires a Loxone Miniserver with firmware version 11.2 or higher.\n\n## Authentication\n\nUses token authentication with the Miniserver. Automatically attempts token refresh before expiry.\n\n## Usage examples\n\n```ts\nimport { AnsiLogger, LogLevel, TimestampFormat } from \"node-ansi-logger\";\nimport LoxoneClient from \"./LoxoneClient.js\";\n\nlet log = new AnsiLogger({logName: \"workbench\", logTimestampFormat: TimestampFormat.TIME_MILLIS});\n\n// instantiate the client\nlet client = new LoxoneClient(\"192.168.1.253:80\", \"user\", \"pass\");\n\n// sets log level to debug for more verbose logging\nclient.setLogLevel(LogLevel.DEBUG);\n\n// subscribe to basic events\nclient.on('disconnected', () =\u003e {\n    log.warn('Loxone client disconnected');\n});\nclient.on('error', (error) =\u003e {\n    log.error(`Loxone client error: ${error.message}`, error);\n});\n\n// initiate connection\nawait client.connect();\n\n// gets acquired token\nconst token = client.auth.tokenHandler.token; \n\n// disconnects and skips invalidation of token\nawait client.disconnect(true); \n\n// uses supplied token for auth instead of acquiring a new one\nawait client.connect(token); \n\n// sets a switch to on\nawait client.control(\"90f7abe3-8772-476d-b1dd-a5c1c4cf1ed9\", \"on\");\n\n// subscribe to Loxone value updates\nclient.on('event_value', (event) =\u003e {\n    log.info(`Received value event: ${event.uuid.stringValue}`);\n    log.info(`  Room: ${event.state?.parentControl?.room?.name}`);\n    log.info(`  Control: ${event.state?.parentControl?.name}`);\n    log.info(`  State: ${event.state?.name}`);\n    log.info(`  Event path: ${event.toPath()}`);\n    log.info(`  Full event: ${event.toString()}`);\n});\n\n// initiates streaming of events\nawait client.enablesUpdates(); \n\n// disconnects and kills token\nawait client.disconnect(); \n```\n\nThis will yield a log output similar to:\n\n```\n...\n[09:04:59.568] [LoxoneClient] Loxone event: Not Assigned/Control/Subcontrol/total = 2446.4848200150127\n[09:04:59.568] [workbench] Received value event: 1cc4333c-02c9-60ec-05ff6d4c46418939\n[09:04:59.569] [workbench]   Room: Not Assigned\n[09:04:59.569] [workbench]   Control: Control/Subcontrol\n[09:04:59.569] [workbench]   State: total\n[09:04:59.570] [workbench]   Event path: Not Assigned/Control/Subcontrol/total\n[09:04:59.570] [workbench]   Full event: Not Assigned/Control/Subcontrol/total = 2446.4848200150127\n...\n```\n\n## API surface\n\n### `LoxoneClient`\n\nKey entrypoint to the module.\n\n```ts\n    LoxoneClient(\n        host: string,\n        username: string,\n        password: string,\n        clientOptions: Partial\u003cLoxoneClientOptions\u003e\n    )\n```\n\n#### Parameters\n\n|parameter|description|\n|--|--|\n|host|IP address or hostname of the Loxone Miniserver|\n|username|username to use|\n|password|password for the user|\n|clientOptions.autoReconnectEnabled|optional parameter to override the default behavior of automatically reconnecting on failure/disconnection|\n|clientOptions.keepAliveEnabled|optional parameter to override the default behavior of enabling a 15 second keepalive\n|clientOptions.messageLogEnabled|optional parameter to override the default behavior of enabling a logging of messages and responses\n|clientOptions.logAllEvents|optional parameter to log all value and text update events to the console\n|clientOptions.maintainLatestEvents|optional paraneter to override the default behavior of maintaining the latest event for each control|\n\nInstantiating a `LoxoneClient` instance does not trigger any network communication.\n\n### `LoxoneClient.connect()`\n\nInitiates the connection to the Loxone Miniserver, negotiates session keys and encryption parameters, as well as attempts token authentication.\n\nGoes through the following sequence\n1. Wire up events so LoxoneClient starts emitting connection and Loxone related events\n1. Checks the Loxone Miniserver generation and firmware version \n1. Connects the WebSocket connection\n1. Performs key exchange and authentication, and schedules automatic token refresh\n1. Enables keepalive (unless disabled by `clientOptions.keepAliveEnabled`)\n\n#### Parameters\n\n```ts\nasync connect(existingToken: string = \"\")\n```\n|parameter|description|\n|--|--|\n|existingToken|if supplied, uses the supplied token instead of acquiring a new one|\n\n\n### `LoxoneClient.disconnect()`\n\nDisconnects the connection and cleans up internal states.\n\n#### Parameters\n\n```ts\nasync disconnect(preserveToken: boolean = false)\n```\n\n|parameter|description|\n|--|--|\n|preserveToken|optional parameter to skip killing the obtained token so it remains valid after disconnection|\n\n\n### `LoxoneClient.getStructureFile()`\n\nRetrieves the Loxone structure file (`LoxAPP3.json`)\n\n#### Parameters\n\n```ts\nasync getStructureFile()\n```\n\n### `LoxoneClient.parseStructureFile()`\n\nParses the Loxone structure file (`LoxAPP3.json`). After calling this method, event updates will contain enriched information about the room, control and states. Each `State` of all `Control`s will also start remembering the latest event received (unless disabled by `clientOptions.maintainLatestEvents`)\n\n#### Parameters\n\n```ts\nasync parseStructureFile()\n```\n\n\n### `LoxoneClient.enableUpdates()`\n\nEnables the streaming of binary event updates.\n\n#### Parameters\n\n```ts\nasync enableUpdates()\n```\n\n### `LoxoneClient.sendTextCommand()`\n\nSends a text command to the Miniserver and waits for the response till timeout (default: 5s, overridable). Automatically applies Command Encryption as needed.\n\n#### Parameters\n\n```ts\nasync sendTextCommand(command: string, timeoutOverride = this.COMMAND_TIMEOUT): Promise\u003cTextMessage\u003e\n```\n\n|parameter|description|\n|--|--|\n|command|The Loxone command to execute|\n|timeoutOverride|optional parameter allowing override of the default 5s timeout. Unit is milliseconds|\n\n#### Returns\n\n`TextMessage` object with the response to the command, or an exception.\n\n\n### `LoxoneClient.sendFileCommand()`\n\nRetrieves a file from the Miniserver and waits for the response till timeout (default: 5s, overridable). \n\n#### Parameters\n\n```ts\nasync sendFileCommand(filename: string, timeoutOverride = this.COMMAND_TIMEOUT): Promise\u003cFileMessage\u003e\n```\n\n|parameter|description|\n|--|--|\n|filename|Filename of the file to be retrieved|\n|timeoutOverride|optional parameter allowing override of the default 5s timeout. Unit is milliseconds|\n\n#### Returns\n\n`FileMessage` object with the file contents, or an exception.\n\n\n### `LoxoneClient.control()`\n\nExecutes a command on a Loxone control identified by its UUID and waits for the response till timeout (default: 5s, overridable)\n\nSee the Loxone [structure file](https://www.loxone.com/wp-content/uploads/datasheets/StructureFile.pdf) for documentation on possible commands.\n\n#### Parameters\n\n```ts\nasync control(uuid: UUID | string, command: string, timeoutOverride = this.COMMAND_TIMEOUT): Promise\u003cTextMessage\u003e\n```\n\n|parameter|description|\n|--|--|\n|uuid|UUID of the Loxone control to operate|\n|command|The command to send|\n|timeoutOverride|optional parameter allowing override of the default 5s timeout. Unit is milliseconds|\n\n#### Returns\n\n`TextMessage` object with the result of the operation, or an exception.\n\n\n### `LoxoneClient.setLogLevel()`\n\nSets the log level. By default it is set to INFO.\n\n#### Parameters\n\n```ts\nsetLogLevel(level: LogLevel)\n```\n|parameter|description|\n|--|--|\n|level|Loglevel to set logging to. Uses the `node-ansi-logger` module|\n\n### `LoxoneClient.addUuidToWatchList()`\n\nAdds UUIDs to the watch list. Value and text update events will only be emitted for these UUIDs. If the watchlist is empty, all events will be emitted. \n\n#### Parameters\n\n```ts\naddUuidToWatchList(uuid: string | string[])\n```\n|parameter|description|\n|--|--|\n|uuid|UUID string or array of strings to add to the watchlist|\n\n### `LoxoneClient.removeUuidFromWatchList()`\n\nRemoves UUIDs from the watch list. \n\n#### Parameters\n\n```ts\nremoveUuidFromWatchList(uuid: string | string[])\n```\n|parameter|description|\n|--|--|\n|uuid|UUID string or array of strings to remove from the watchlist|\n\n### `LoxoneClient.checkToken()`\n\nChecks whether the token is still valid.\n\n#### Parameters\n\n```ts\nasync checkToken(token: string = \"\")\n```\n\n|parameter|description|\n|--|--|\n|token|If supplied, checks the supplied token instead of the remembered (active) one|\n\n### `LoxoneClient.refreshToken()`\n\nRefreshes the active token if it is still valid. If not, attempts to acquire a new one.\n\n#### Parameters\n\n```ts\nasync refreshToken()\n```\n\n## Events\n\nThe `LoxoneClient` emits the following events:\n\n```ts\n  connected: () =\u003e void;\n```\nFires when the connection is successfully established.\n\n```ts\n  authenticated: () =\u003e void;\n```\nFires when authentication was successful.\n\n```ts\n  ready: () =\u003e void;\n```\nFires when `LoxoneClient` is ready to receive commands.\n\n```ts\n  disconnected: (reason: string) =\u003e void;\n```\n\nFires when the underlying WebSocket is disconnected.\n\n```ts\n  error: (err: Error) =\u003e void;\n```\n\nFires when a WebSocket error is encountered.\n\n```ts\n  header: (header: ParsedHeader) =\u003e void;\n```\nFires when a header message is received.\n\n```ts\n  keepalive: (header: ParsedHeader) =\u003e void;\n```\nFires when a keepalive message is received.\n\n```ts\n  text_message: (text: TextMessage) =\u003e void;\n```\nFires when a text message is received on the WebSocket channel.\n```ts\n  file_message: (file: FileMessage) =\u003e void;\n```\nFires when a file message is received on the WebSocket channel.\n\n```ts\n  event_table_values: (eventTable: LoxoneValueEvent[]) =\u003e void;\n  event_table_text: (eventTable: LoxoneTextEvent[]) =\u003e void;\n  event_table_day_timer: (eventTable: LoxoneDayTimerEvent[]) =\u003e void;\n  event_table_weather: (eventTable: LoxoneWeatherEvent[]) =\u003e void;\n```\nFires when an event update message is received on the WebSocket channel. EventTables can contain multiple update events of the same kind.\n```ts\n  stateChanged: (newState: string) =\u003e void;\n```\nFires when the `LoxoneClient` changes its state. Possible states are:\n- disconnected\n- disconnecting\n- connecting\n- connected\n- authenticating\n- authenticated\n- ready\n- reconnecting\n- error\n\n```ts\n  event_value: (event: LoxoneValueEvent) =\u003e void;\n  event_text: (event: LoxoneTextEvent) =\u003e void;\n```\nFires when Loxone value or text update events are received. Events can be filtered using the watchlist functionality (`addUuidToWatchList()` and `removeUuidFromWatchList()`). If the watchlist contains any items, events `event_value` and `event_text` events are only emitted for the UUIDs that are on the watchlist. If the watchlist is empty, events are emitted for all value and text updates.\n\n## Disclaimer\n\nWhile the author took special care to follow Loxone [official documentation](https://www.loxone.com/wp-content/uploads/datasheets/CommunicatingWithMiniserver.pdf), use this module at your own risk.\n\n## Acknowledgements, credits\n\nThis module is heavily inspired by and based on the `node-lox-ws-api` module: https://github.com/alladdin/node-lox-ws-api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrasg%2Floxone-ts-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrasg%2Floxone-ts-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrasg%2Floxone-ts-api/lists"}