Update doc

3 years ago · 6f8b6f6ae9
1 changed files with 112 additions and 60 deletions
--- a/README.md
+++ b/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