{"id":21059883,"url":"https://github.com/flochtililoch/lirc-state-api","last_synced_at":"2025-05-16T00:33:58.357Z","repository":{"id":11033079,"uuid":"68076462","full_name":"flochtililoch/lirc-state-api","owner":"flochtililoch","description":"API to manipulate the states of infrared controlled devices","archived":false,"fork":false,"pushed_at":"2023-11-10T00:52:45.000Z","size":160,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-26T07:45:34.215Z","etag":null,"topics":["api","json","lirc"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/flochtililoch.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}},"created_at":"2016-09-13T05:14:08.000Z","updated_at":"2023-09-10T02:49:54.000Z","dependencies_parsed_at":"2024-11-13T16:52:11.983Z","dependency_job_id":"71685eb4-2b0f-4786-9700-be3932d5e0cf","html_url":"https://github.com/flochtililoch/lirc-state-api","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flochtililoch%2Flirc-state-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flochtililoch%2Flirc-state-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flochtililoch%2Flirc-state-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flochtililoch%2Flirc-state-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flochtililoch","download_url":"https://codeload.github.com/flochtililoch/lirc-state-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254447882,"owners_count":22072755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api","json","lirc"],"created_at":"2024-11-19T17:13:42.910Z","updated_at":"2025-05-16T00:33:53.329Z","avatar_url":"https://github.com/flochtililoch.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LIRC-STATE-API\n\n## tl;dr\nAPI to manipulate the states of infrared controlled devices.\n\n*This is a work-in-progress*\n\n## Description\nThe purpose of this module is to offer an API allowing manipulation of dumb, infrared controlled devices (i.e. TVs, fan, etc...). Sending infra-red signals to change the state of a device, as well as listening for infra-red signals from these devices' remote controls is done using [LIRC](http://www.lirc.org). Keeping track of these devices' states changes is done using a javascript implementation of [Finite-State Machine](https://en.wikipedia.org/wiki/Finite-state_machine).\nAssumptions here is made that devices to control with this API have a finite number of states.\nCurrently, two types of states are modeled: *Linear* and *Loop*. These states are represented by an array of every possible values (at least two values required).\n\n### Linear state\nUseful to represent an information that is changed in a linear way via two remote control buttons (usually increment / decrement).\n\n### Loop state\nUseful to represent an information that is is changed via a single button. Actions on this button only moves the state to its next possible value, until the end is reached. Next press brings the state back to its first value.\n\n#### Examples:\n\n*A TV can have:*\n- **power** state with `on` and `off` values. (*loop*)\n- **source** state with `tv`, `hdmi1`, `hdmi2`, `composite` values. (*loop*)\n- **mute** state with `on` and `off` values. (*loop*)\n- **volume** state with a range from `1` to `50`. (*linear*)\n\n*A Fan can have:*\n- **power** state with `on` and `off` values. (*loop*)\n- **rotate** state with `on` and `off` values. (*loop*)\n- **air** state with a range from `1` to `10`. (*linear*)\n\n*A Speaker can have:*\n- **power** state with `on` and `off` values. (*loop*)\n- **mute** state with `on` and `off` values. (*loop*)\n- **volume** state with a range from `1` to `50`. (*linear*)\n\n## Setup\n\n### Pre-requisite\nLIRC must be up and running. See [Open Source Universal Remote](http://opensourceuniversalremote.com) for details on how to set it up. Alternatively, you can also run LIRC on a [docker image on a Raspberry pi](https://hub.docker.com/r/flochtililoch/armv6l-lirc/) / [Raspberry pi 2/3](https://hub.docker.com/r/flochtililoch/armv7l-lirc/).\n\n### Configuration file\nThe configuration is expressed in a JSON file via an array of javascript objects, each representing a device.\n\n### Device configuration\n\n#### Required properties:\n- `id`: *string* used as a resource identifier.\n- `lirc_id`: *string* maps to the remote control id as specified in the LIRC configuration.\n- `name`: *string* user friendly name representing the device.\n- `states`: *array* [state objects](#state-configuration).\n\n#### Optional properties:\n- `lircd_address`: *string* (host[:port]) configure a host to send IR command to (see address option at http://lirc.org/html/irsend.html#lbAE)\n- `send_delay`: *integer* (milliseconds, default to 500).\n- `receive_delay`: *integer* (milliseconds, default to 0).\n- `dependencies`: *array* [dependency objects](#dependency-configuration).\n\n### State configuration\n\n#### Required properties:\n- `id`: *string* used as a resource identifier.\n- `type`: *string* Possible values: [`loop`](#loop-state), [`linear`](#linear-state)\n- `values`: *array* List of all values the state can take.\n- `keys`: *object*. [keys object](#keys-configuration).\n\n#### Optional properties:\n- `send_for`: *number* (milliseconds) - when specified, will continuously emit the key signal for the specified time.\n\n### Keys configuration\n\n#### Required properties for states of type `loop`:\n- `next`: *string* LIRC key id that moves the state to its next value.\n\n#### Required properties for states of type `linear`:\n- `up`: *string* LIRC key id that move the state up.\n- `down`: *string* LIRC key id that move the state down.\n\n### Dependency configuration\n\n#### Required properties:\n- `states`: *array* of states with dependencies.\n- `depends`: *array*  of dependencies objects, containing two keys: `id` (matching the actual state `id`) and values (list of values the state should be set to).\n\n\n### Example configuration\n```json\n[\n  {\n    \"id\": \"tv\",\n    \"lirc_id\": \"TV\",\n    \"lircd_address\": \"lirc.local:8765\",\n    \"name\": \"TV\",\n    \"send_delay\": 500,\n    \"receive_delay\": 0,\n    \"states\": [\n      {\n        \"id\": \"power\",\n        \"type\": \"loop\",\n        \"values\": [false, true],\n        \"keys\": {\n          \"next\": \"KEY_POWER\"\n        }\n      },\n      {\n        \"id\": \"mute\",\n        \"type\": \"loop\",\n        \"values\": [false, true],\n        \"keys\": {\n          \"next\": \"KEY_MUTE\"\n        }\n      },\n      {\n        \"id\": \"volume\",\n        \"type\": \"linear\",\n        \"values\": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],\n        \"keys\": {\n          \"up\": \"KEY_VOLUMEUP\",\n          \"down\": \"KEY_VOLUMEDOWN\"\n        }\n      },\n      {\n        \"id\": \"source\",\n        \"type\": \"loop\",\n        \"values\": [\"tv\", \"hdmi1\", \"hdmi2\", \"composite\"],\n        \"keys\": {\n          \"next\": \"KEY_CYCLEWINDOWS\"\n        }\n      }\n    ],\n    \"dependencies\": [\n      {\n        \"states\": [\"mute\", \"volume\", \"source\"],\n        \"depends\": [\n          {\n            \"id\": \"power\",\n            \"values\": [true]\n          }\n        ]\n      },\n      {\n        \"states\": [\"volume\"],\n        \"depends\": [\n          {\n            \"id\": \"mute\",\n            \"values\": [false]\n          }\n        ]\n      }\n    ]\n  },\n  {\n    \"id\": \"fan\",\n    \"lirc_id\": \"FAN\",\n    \"name\": \"Fan\",\n    \"states\": [\n      {\n        \"id\": \"power\",\n        \"type\": \"loop\",\n        \"values\": [false, true],\n        \"send_for\": 500,\n        \"keys\": {\n          \"next\": \"KEY_POWER\"\n        }\n      },\n      {\n        \"id\": \"rotate\",\n        \"type\": \"loop\",\n        \"values\": [false, true],\n        \"keys\": {\n          \"next\": \"KEY_MOVE\"\n        }\n      },\n      {\n        \"id\": \"air\",\n        \"type\": \"linear\",\n        \"values\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],\n        \"keys\": {\n          \"up\": \"BTN_GEAR_UP\",\n          \"down\": \"BTN_GEAR_DOWN\"\n        }\n      },\n      {\n        \"id\": \"timer\",\n        \"type\": \"linear\",\n        \"values\": [\"off\", \"15min\", \"30min\", \"45min\"],\n        \"keys\": {\n          \"up\": \"KEY_UP\",\n          \"down\": \"KEY_DOWN\"\n        }\n      }\n    ],\n    \"dependencies\": [\n      {\n        \"states\": [\"rotate\", \"air\", \"timer\"],\n        \"depends\": [\n          {\n            \"id\": \"power\",\n            \"values\": [true]\n          }\n        ]\n      }\n    ]\n  }\n]\n```\n\n### Run\n\n```bash\n$ lirc-state-api -c=/path/to/config.json [-p=1234]\n```\n\n## Model\n\n### Devices\n\nRepresentation of the devices LIRC remotes are controlling.\nEach device has an identifier, a given name, and a list of states.\n\n### States\n\nRepresentation of various states devices can have.\nA state has an identifier, a type and a list of values.\n\n\n## HTTP REST API\n\n### Devices Index\n\n#### Request:\n\n```\nGET /devices\n```\n\n#### Response:\n\n```\n{\n  \"devices\": [\n    {\n      \"id\": ...,\n      \"name\": ...,\n      \"states\": [\n        {\n          \"id\": ...,\n          \"value\": ...\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Show Device\n\n#### Request:\n\n```\nGET /devices/:id\n```\n\n#### Response:\n\n```\n{\n  \"id\": ...,\n  \"name\": ...,\n  \"states\": [\n    {\n      \"id\": ...,\n      \"value\": ...\n    },\n    ...\n  ]\n}\n```\n\n### Show Device's States\n\n#### Request:\n\n```\nGET /devices/:id/states\n```\n\n#### Response:\n\n```\n[\n  {\n    \"id\": ...,\n    \"value\": ...\n  },\n  ...\n]\n```\n\n### Update Device States\n\n#### Request:\n\n```\nPATCH /devices/:id/states\n```\n\n```\n[\n  {\n    \"id\": ...,\n    \"value\": ...\n  },\n  ...\n]\n```\n\n### Update Device State\n\n#### Request:\n\n```\nPUT /:id/states/:id\n```\n\n```\n{\n  \"value\": ...\n}\n```\n\n## TODO\nSee project [V1 Dev](https://github.com/flochtililoch/lirc-state-api/projects/1).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflochtililoch%2Flirc-state-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflochtililoch%2Flirc-state-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflochtililoch%2Flirc-state-api/lists"}