Browse Source

Update doc

7rc0
Laurent Kislaire 3 years ago
parent
commit
6f8b6f6ae9
  1. 172
      README.md

172
README.md

@ -5,72 +5,14 @@
* Full API coverage
* Https and Mdns discovery
* Thin client wrapper library (<200 lines)
* CLI script example to access any command
* Small script to perform most tasks
[![pipeline status](https://framagit.org/sun/pyfbx/badges/master/pipeline.svg)](https://framagit.org/sun/pyfbx/commits/master)
[![coverage report](https://framagit.org/sun/pyfbx/badges/master/coverage.svg)](https://framagit.org/sun/pyfbx/commits/master)
## Script
A script called pyfbx is installed and can be used like this:
To register the application:
```shell
$ pyfbx SuperAppId
```
Once registration is done on the device, write down the application token.
Using this app token, acquire a session token to execute a test command.
```shell
$ pyfbx -t '<TOKEN>' SuperAppId
$ pyfbx -t 'f:<TOKEN_FILE>' SuperAppId
```
You can run any commands on the freebox and retrieve complete result or single value
```shell
$ pyfbx -t f:/home/foo/token.txt SuperAppId -c 'Contacts.Create_a_contact(\
post_data={"display_name": "Sandy Kilo", "first_name": "Sandy", "last_name":"Kilo"})'
{ 'birthday': '',
'company': '',
'display_name': 'Sandy Kilo',
'first_name': 'Sandy',
'id': 17,
'last_name': 'Kilo',
'last_update': 1554378898,
'notes': '',
'photo_url': ''}
$ pyfbx -t f:token.txt -u https://0s2efr3i.fbxos.fr:15628 id -c "Connection.Get_the_current_Connection_status()['rate_up']"
1700
```
_Note_ : Don't forget to escape token and command with quotes.
The complete script help is:
```shell
pyfbx -h
usage: pyfbx [-h] [-c COMMAND] [-t TOKEN] [-v] [-n] [-u URL] app_id
positional arguments:
app_id application identifier
optional arguments:
-h, --help show this help message and exit
-c COMMAND, --command COMMAND
command, defaults to
System.Get_the_current_system_info()
-t TOKEN, --token TOKEN
token (or f:<filename>)
-v, --verbose increase verbosity to INFO, use twice for DEBUG
-n, --http Disable MDNS and use http known address
-u URL, --url URL specific url to query
```
## Library usage
The library is available to create your own scripts.
The REST API is generated at runtime with the creation of class attributes for all Freebox subsystems.
```python
@ -120,6 +62,116 @@ Access_a_given_contact_entry(id) method of pyfbx.client.Contacts instance
>>> f.mksession()
```
## Script
The included script can perform a lot of tasks.
### Basics
```shell
$ pyfbx -h
usage: pyfbx [-h] [-a APP_ID] [-t TOKEN] [-v] [-n] [-j] [-d DELAY] [-u URL]
[-s SEND] [-c COMMAND]
optional arguments:
-h, --help show this help message and exit
-a APP_ID, --app_id APP_ID
application identifier
-t TOKEN, --token TOKEN
token (or f:<filename>)
-v, --verbose increase verbosity to INFO, use twice for DEBUG
-n, --http disable MDNS and use http known address
-j, --json json output
-d DELAY, --delay DELAY
cylically send command (number of seconds)
-u URL, --url URL specific url to query
-s SEND, --send SEND url to send json to
-c COMMAND, --command COMMAND
command, defaults to
System.Get_the_current_system_info()
```
First, register the application:
```shell
$ pyfbx SuperAppId
```
Once registration is done on the device, write down the application token.
You can also create a file with token as first line and application Id as second.
Using this app token, acquire a session token to execute a test command.
```shell
$ pyfbx -t '<TOKEN>' SuperAppId
$ pyfbx -t 'f:<TOKEN_FILE>' SuperAppId
```
### Advanced
You can run any commands on the freebox and retrieve complete result or single value
```shell
$ pyfbx -t f:/home/foo/token.txt SuperAppId -c 'Contacts.Create_a_contact(\
post_data={"display_name": "Sandy Kilo", "first_name": "Sandy", "last_name":"Kilo"})'
{ 'birthday': '',
'company': '',
'display_name': 'Sandy Kilo',
'first_name': 'Sandy',
'id': 17,
'last_name': 'Kilo',
'last_update': 1554378898,
'notes': '',
'photo_url': ''}
$ pyfbx -u https://0s2efr3i.fbxos.fr:15628 id -c "Connection.Get_the_current_Connection_status()['rate_up']" -t f:token.txt
1700
```
With the delay option, commands can be sent cyclically:
```shell
$ pyfbx -d 1 -c "Connection.Get_the_current_Connection_status()['rate_up']" -t f:token.txt
42460
50710
58890
53120
53400
```
With the send option, result can be sent to a remote URL.
In the following, the result is sent cyclically to example.com in json format.
```shell
pyfbx -j -s http://example.com/values -d 10 -c "Connection.Get_the_current_Connection_status()" -t f:token.txt
```
It's possible to execute several commands.
Here, two commands are sent cyclically and results sent to an URL.
```shell
pyfbx -c 'System.Get_the_current_system_info()' -c 'Connection.Get_the_current_Connection_status()' -d 10 -j -s http://localhost:8182/telegraf -t f:token.txt
```
Telegraf http listener v2 input plugin with json format can be used to plot data in realtime.
_Note_ : Don't forget to escape token and command with quotes.
### Telegraf plots
You can use a telegraph configuration in /etc/telegraf/telegraf.d/freebox:
```
[[inputs.http_listener_v2]]
service_address = ":8182"
path = "/telegraf"
methods = ["POST"]
read_timeout = "10s"
write_timeout = "10s"
max_body_size = "5KB"
data_format = "json"
name_override = "pyfbx"
```
## Developpment
### Testing

Loading…
Cancel
Save