Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flochtililoch/lirc-state-api
API to manipulate the states of infrared controlled devices
https://github.com/flochtililoch/lirc-state-api
api json lirc
Last synced: about 5 hours ago
JSON representation
API to manipulate the states of infrared controlled devices
- Host: GitHub
- URL: https://github.com/flochtililoch/lirc-state-api
- Owner: flochtililoch
- License: mit
- Created: 2016-09-13T05:14:08.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-11-10T00:52:45.000Z (about 1 year ago)
- Last Synced: 2024-11-13T16:52:41.182Z (6 days ago)
- Topics: api, json, lirc
- Language: JavaScript
- Homepage:
- Size: 156 KB
- Stars: 10
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LIRC-STATE-API
## tl;dr
API to manipulate the states of infrared controlled devices.
*This is a work-in-progress*
## Description
The 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).
Assumptions here is made that devices to control with this API have a finite number of states.
Currently, 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).
### Linear state
Useful to represent an information that is changed in a linear way via two remote control buttons (usually increment / decrement).
### Loop state
Useful 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.
#### Examples:
*A TV can have:*
- **power** state with `on` and `off` values. (*loop*)
- **source** state with `tv`, `hdmi1`, `hdmi2`, `composite` values. (*loop*)
- **mute** state with `on` and `off` values. (*loop*)
- **volume** state with a range from `1` to `50`. (*linear*)
*A Fan can have:*
- **power** state with `on` and `off` values. (*loop*)
- **rotate** state with `on` and `off` values. (*loop*)
- **air** state with a range from `1` to `10`. (*linear*)
*A Speaker can have:*
- **power** state with `on` and `off` values. (*loop*)
- **mute** state with `on` and `off` values. (*loop*)
- **volume** state with a range from `1` to `50`. (*linear*)
## Setup
### Pre-requisite
LIRC 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/).
### Configuration file
The configuration is expressed in a JSON file via an array of javascript objects, each representing a device.
### Device configuration
#### Required properties:
- `id`: *string* used as a resource identifier.
- `lirc_id`: *string* maps to the remote control id as specified in the LIRC configuration.
- `name`: *string* user friendly name representing the device.
- `states`: *array* [state objects](#state-configuration).
#### Optional properties:
- `lircd_address`: *string* (host[:port]) configure a host to send IR command to (see address option at http://lirc.org/html/irsend.html#lbAE)
- `send_delay`: *integer* (milliseconds, default to 500).
- `receive_delay`: *integer* (milliseconds, default to 0).
- `dependencies`: *array* [dependency objects](#dependency-configuration).
### State configuration
#### Required properties:
- `id`: *string* used as a resource identifier.
- `type`: *string* Possible values: [`loop`](#loop-state), [`linear`](#linear-state)
- `values`: *array* List of all values the state can take.
- `keys`: *object*. [keys object](#keys-configuration).
#### Optional properties:
- `send_for`: *number* (milliseconds) - when specified, will continuously emit the key signal for the specified time.
### Keys configuration
#### Required properties for states of type `loop`:
- `next`: *string* LIRC key id that moves the state to its next value.
#### Required properties for states of type `linear`:
- `up`: *string* LIRC key id that move the state up.
- `down`: *string* LIRC key id that move the state down.
### Dependency configuration
#### Required properties:
- `states`: *array* of states with dependencies.
- `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).
### Example configuration
```json
[
{
"id": "tv",
"lirc_id": "TV",
"lircd_address": "lirc.local:8765",
"name": "TV",
"send_delay": 500,
"receive_delay": 0,
"states": [
{
"id": "power",
"type": "loop",
"values": [false, true],
"keys": {
"next": "KEY_POWER"
}
},
{
"id": "mute",
"type": "loop",
"values": [false, true],
"keys": {
"next": "KEY_MUTE"
}
},
{
"id": "volume",
"type": "linear",
"values": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"keys": {
"up": "KEY_VOLUMEUP",
"down": "KEY_VOLUMEDOWN"
}
},
{
"id": "source",
"type": "loop",
"values": ["tv", "hdmi1", "hdmi2", "composite"],
"keys": {
"next": "KEY_CYCLEWINDOWS"
}
}
],
"dependencies": [
{
"states": ["mute", "volume", "source"],
"depends": [
{
"id": "power",
"values": [true]
}
]
},
{
"states": ["volume"],
"depends": [
{
"id": "mute",
"values": [false]
}
]
}
]
},
{
"id": "fan",
"lirc_id": "FAN",
"name": "Fan",
"states": [
{
"id": "power",
"type": "loop",
"values": [false, true],
"send_for": 500,
"keys": {
"next": "KEY_POWER"
}
},
{
"id": "rotate",
"type": "loop",
"values": [false, true],
"keys": {
"next": "KEY_MOVE"
}
},
{
"id": "air",
"type": "linear",
"values": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"keys": {
"up": "BTN_GEAR_UP",
"down": "BTN_GEAR_DOWN"
}
},
{
"id": "timer",
"type": "linear",
"values": ["off", "15min", "30min", "45min"],
"keys": {
"up": "KEY_UP",
"down": "KEY_DOWN"
}
}
],
"dependencies": [
{
"states": ["rotate", "air", "timer"],
"depends": [
{
"id": "power",
"values": [true]
}
]
}
]
}
]
```
### Run
```bash
$ lirc-state-api -c=/path/to/config.json [-p=1234]
```
## Model
### Devices
Representation of the devices LIRC remotes are controlling.
Each device has an identifier, a given name, and a list of states.
### States
Representation of various states devices can have.
A state has an identifier, a type and a list of values.
## HTTP REST API
### Devices Index
#### Request:
```
GET /devices
```
#### Response:
```
{
"devices": [
{
"id": ...,
"name": ...,
"states": [
{
"id": ...,
"value": ...
}
]
}
]
}
```
### Show Device
#### Request:
```
GET /devices/:id
```
#### Response:
```
{
"id": ...,
"name": ...,
"states": [
{
"id": ...,
"value": ...
},
...
]
}
```
### Show Device's States
#### Request:
```
GET /devices/:id/states
```
#### Response:
```
[
{
"id": ...,
"value": ...
},
...
]
```
### Update Device States
#### Request:
```
PATCH /devices/:id/states
```
```
[
{
"id": ...,
"value": ...
},
...
]
```
### Update Device State
#### Request:
```
PUT /:id/states/:id
```
```
{
"value": ...
}
```
## TODO
See project [V1 Dev](https://github.com/flochtililoch/lirc-state-api/projects/1).