Specification work
This commit is contained in:
David Todd
parent
43e1c335d6
commit
765de261e8
|
|
@ -2,86 +2,9 @@
|
|||
|
||||
This is a small python server that uses [Bottle](https://bottlepy.org) to provide an encrypted REST interface to the pixo firmware (and future compatibles).
|
||||
|
||||
## API->pixo Definition
|
||||
## Server Specification
|
||||
|
||||
TBD
|
||||
|
||||
## Web->API Definition
|
||||
|
||||
TBD
|
||||
|
||||
## Telegram Bot->API Definition
|
||||
|
||||
Initial implementation will use [Python Telegram Bot](https://github.com/python-telegram-bot/python-telegram-bot) to create a Telegram interface that accepts
|
||||
- Commands
|
||||
- Images
|
||||
- Animations
|
||||
- Videos (This one is low priority/might not happen)
|
||||
|
||||
### Commands
|
||||
|
||||
For all commands that accept, but aren't supplied a specific input, the bot will automatically provide context-aware options (such as names of enrolled devices) or inputs (custom keyboard/number keyboard/normal keyboard)
|
||||
|
||||
- `/send [name/id] *ATTACHMENT*` - Sends the attached media (if supported) to the selected device.
|
||||
- If `/auto` is configured for any device, simply forwarding media to the bot will `/send` it to the device(s)
|
||||
- `/newdevice [name/id]` - Alias of `/device new [name/id]`, if no name provided, starts "New Device Wizard", a series of `/device` sub-commands to get started
|
||||
- Runs through these sub-commands
|
||||
1. `/connect`
|
||||
2. `/data` - Name, resolution, and type
|
||||
3. `/auto` - Read `/send` above
|
||||
4. `/protect` - Prevent further changes to the device until turned off, unique per device pin
|
||||
- Does not allow changing of `/config` commands
|
||||
- Does not allow `/sensor` commands, the bot will poll for sensor endpoints automatically. These sensors can be later removed by
|
||||
1. `/device edit name`
|
||||
2. `/sensor del sensor-name`
|
||||
- `/deldevice [name/id]` - Alias of `/device del [name/id]`
|
||||
- If the device has `/protect` turned on, the user must enter the pin before confirming the deletion
|
||||
- `/ping [name/id]` - Pings the selected device and responds with how long it took/offline.
|
||||
|
||||
- `/device [new/edit/del] [name/id]` - New enrolls a new device, Del will purge the device from the database, Edit engages **Device Configuration Mode** with the following available commands.
|
||||
- `/exit` - Returns to normal mode
|
||||
1. If `/protect` is not on, the user will be asked if they want to enable it
|
||||
|
||||
- `/connect` - Connects to the device with various options
|
||||
1. `/device` (default) - The device will connect to the server from time to time (configurable in device settings). Generates a shared secret to be inputted in device settings
|
||||
2. `/discover` - If the device is on the same network as the server, we can attempt autodiscovery and the server will establish a connection
|
||||
- The device should prompt for acceptance, either via button press or other UI
|
||||
3. `/direct` - If the device can be accessed with a hostname/domain/IP:port, the server will establish a connection
|
||||
- The device should prompt for acceptance, either via button press of other UI
|
||||
|
||||
- `/data` - Provides meta-data about the device
|
||||
1. `/resolution` - Dimensions of device. Expects to be in format like 16x16
|
||||
2. `/name` - Sets a unique to you name for the device, any length
|
||||
3. `/type` - What type of device is it (eg. pixo-pixel)
|
||||
- `/auto [on/off]` - If on, the device will automatically recieve any media sent to the bot, if the media is supported. Default off
|
||||
|
||||
- `/protect [on/off/clear]` - User will be prompted to input a pin that will not be displayed. Prevents further changes to **all device configuration**
|
||||
1. This does not prevent reading of known sensors, use `/sensor del [name]` to remove and make them inaccessable when `/protect` is off
|
||||
- This prevents deletion and addition of sensors if enabled
|
||||
2. When sent again, the user will be asked if they want to remove the protection
|
||||
3. If the user attempts to delete the device, and `/protect` is on, they will first be prompted for their device pin
|
||||
4. If the user attempts to edit the device, they will be told to turn off `/protect` first
|
||||
5. If off, `/protect` will remember the last set pin. Use `/protect clear` to remove the pin
|
||||
|
||||
- `/sensor [add/del] [name] [endpoint]` - If a sensor is not automatically detected, or you wish to remove a sensor, this will communicate to the device and read the value.
|
||||
1. If the device does not have the endpoint, the sensor will not be added
|
||||
- `/read [sensor]` - If the device has the named sensor, read the value and return it
|
||||
1. The sensor can be physical (ie, temperature, gyroscope, etc) or it can be virtual (ie, CPU/MEM utilization, WIFI traffic, etc)
|
||||
- `/poll [sensor] [timer]` - Performs a `/read` every `timer` seconds
|
||||
1. Every new message will include a button to stop the timer/stop button will be available in custom keyboard as priority option
|
||||
|
||||
- `/cmd [cmd] [opts]` - Sends an API request to the selected device with the selected command with options
|
||||
1. These API requests are *in the documetation for the device*
|
||||
- `/config [option] [value]` - If supported, sets/replaces device config option (ex, change wifi, secret key, etc)
|
||||
1. If the device has been `/protect`ed, these changes will fail
|
||||
|
||||
### Images
|
||||
|
||||
When the bot recieves an image, we need to resize it to our matrix resolution
|
||||
|
||||
### Animations
|
||||
|
||||
### Video (maybe)
|
||||
Refer to [specification.md](specification.md) for the API definitions
|
||||
|
||||
# LICENSE
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,100 @@
|
|||
# PixoPython Server API
|
||||
|
||||
This is the specification for the PixoPython Server.
|
||||
|
||||
- API - These are external functions and/or HTTP routes of the server
|
||||
- pixo - This is the HTTP REST API specified by the `pixo firmware`
|
||||
- Telegram Bot - This is a thread of the API server that connects to Telegram as a Bot to recieve media
|
||||
|
||||
## API->pixo Definition
|
||||
|
||||
TBD
|
||||
|
||||
## Web->API Definition
|
||||
|
||||
TBD
|
||||
|
||||
## Telegram Bot->API Definition
|
||||
|
||||
Initial implementation will use [Python Telegram Bot](https://github.com/python-telegram-bot/python-telegram-bot) to create a Telegram interface that accepts
|
||||
- Commands
|
||||
- Images
|
||||
- Animations
|
||||
- Videos (This one is low priority/might not happen)
|
||||
|
||||
### Commands
|
||||
|
||||
For all commands that accept, but aren't supplied a specific input, the bot will automatically provide context-aware options (such as names of enrolled devices) or inputs (custom keyboard/number keyboard/normal keyboard)
|
||||
|
||||
- `/send [name/id] *ATTACHMENT*` - Sends the attached media (if supported) to the selected device.
|
||||
- If `/auto` is configured for any device, simply forwarding media to the bot will `/send` it to the device(s)
|
||||
- `/newdevice [name/id]` - Alias of `/device new [name/id]`, if no name provided, starts "New Device Wizard", a series of `/device` sub-commands to get started
|
||||
- Runs through these sub-commands
|
||||
1. `/connect`
|
||||
2. `/data` - Name, resolution, and type
|
||||
3. `/auto` - Read `/send` above
|
||||
4. `/protect` - Prevent further changes to the device until turned off, unique per device pin
|
||||
- Does not allow changing of `/config` commands
|
||||
- Does not allow `/sensor` commands, the bot will poll for sensor endpoints automatically. These sensors can be later removed by
|
||||
1. `/device edit name`
|
||||
2. `/sensor del sensor-name`
|
||||
- `/deldevice [name/id]` - Alias of `/device del [name/id]`
|
||||
- If the device has `/protect` turned on, the user must enter the pin before confirming the deletion
|
||||
- `/ping [name/id]` - Pings the selected device and responds with how long it took/offline.
|
||||
|
||||
- `/device [new/edit/del] [name/id]` - New enrolls a new device, Del will purge the device from the database, Edit engages **Device Configuration Mode** with the following available commands.
|
||||
- `/exit` - Returns to normal mode
|
||||
1. If `/protect` is not on, the user will be asked if they want to enable it
|
||||
|
||||
- `/connect` - Connects to the device with various options
|
||||
1. `/device` (default) - The device will connect to the server from time to time (configurable in device settings). Generates a shared secret to be inputted in device settings
|
||||
2. `/discover` - If the device is on the same network as the server, we can attempt autodiscovery and the server will establish a connection
|
||||
- The device should prompt for acceptance, either via button press or other UI
|
||||
3. `/direct` - If the device can be accessed with a hostname/domain/IP:port, the server will establish a connection
|
||||
- The device should prompt for acceptance, either via button press of other UI
|
||||
|
||||
- `/data` - Provides meta-data about the device
|
||||
1. `/resolution` - Dimensions of device. Expects to be in format like 16x16
|
||||
2. `/name` - Sets a unique to you name for the device, any length
|
||||
3. `/type` - What type of device is it (eg. pixo-pixel)
|
||||
- `/auto [on/off]` - If on, the device will automatically recieve any media sent to the bot, if the media is supported. Default off
|
||||
|
||||
- `/protect [on/off/clear]` - User will be prompted to input a pin that will not be displayed. Prevents further changes to **all device configuration**
|
||||
1. This does not prevent reading of known sensors, use `/sensor del [name]` to remove and make them inaccessable when `/protect` is off
|
||||
- This prevents deletion and addition of sensors if enabled
|
||||
2. When sent again, the user will be asked if they want to remove the protection
|
||||
3. If the user attempts to delete the device, and `/protect` is on, they will first be prompted for their device pin
|
||||
4. If the user attempts to edit the device, they will be told to turn off `/protect` first
|
||||
5. If off, `/protect` will remember the last set pin. Use `/protect clear` to remove the pin
|
||||
|
||||
- `/sensor [add/del] [name] [endpoint]` - If a sensor is not automatically detected, or you wish to remove a sensor, this will communicate to the device and read the value.
|
||||
1. If the device does not have the endpoint, the sensor will not be added
|
||||
- `/read [sensor]` - If the device has the named sensor, read the value and return it
|
||||
1. The sensor can be physical (ie, temperature, gyroscope, etc) or it can be virtual (ie, CPU/MEM utilization, WIFI traffic, etc)
|
||||
- `/poll [sensor] [timer]` - Performs a `/read` every `timer` seconds
|
||||
1. Every new message will include a button to stop the timer/stop button will be available in custom keyboard as priority option
|
||||
|
||||
- `/cmd [cmd] [opts]` - Sends an API request to the selected device with the selected command with options
|
||||
1. These API requests are *in the documetation for the device*
|
||||
- `/config [option] [value]` - If supported, sets/replaces device config option (ex, change wifi, secret key, etc)
|
||||
1. If the device has been `/protect`ed, these changes will fail
|
||||
|
||||
### Images
|
||||
|
||||
When the bot recieves an image, we need to do the following
|
||||
|
||||
1. Check for any bots that have the `auto` flag enabled, and for those bots
|
||||
- Apply any filters
|
||||
- resize the image to the device resolution
|
||||
- Apply transition to/from this image if applicable
|
||||
- Queue the message to be sent to the device, if verbose mode send message when device recieves it
|
||||
2. Ask user which device they want to send the image to and follow `auto` steps
|
||||
|
||||
### Animations
|
||||
|
||||
Depending on the frame rate, this could be just a bunch of images that get sent through.
|
||||
Perhaps a compression scheme may be needed. May require a bit of processing on the device.
|
||||
|
||||
### Video (maybe)
|
||||
|
||||
Even faster than animations, and generally require a bit of processing on the device
|
||||
Loading…
Reference in New Issue