Freebox thin client
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 5.9KB

11 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
10 months ago
10 months ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189
  1. # Freebox client library
  2. ## Features
  3. * Full API coverage
  4. * Https and Mdns discovery
  5. * Thin client wrapper library (<200 lines)
  6. * Small script to perform most tasks
  7. [![pipeline status](https://framagit.org/sun/pyfbx/badges/master/pipeline.svg)](https://framagit.org/sun/pyfbx/commits/master)
  8. [![coverage report](https://framagit.org/sun/pyfbx/badges/master/coverage.svg)](https://framagit.org/sun/pyfbx/commits/master)
  9. ## Library usage
  10. The library is available to create your own scripts.
  11. The REST API is generated at runtime with the creation of class attributes for all Freebox subsystems.
  12. ```python
  13. >>> from pyfbx import Fbx
  14. >>> f=Fbx() # By default, this will perform MDNS discovery
  15. >>> f=Fbx(nomdns=True) # Use faster http api discovery
  16. >>> f.<TAB>
  17. f.Airmedia f.Download_Config f.Lan f.Rrd f.Upnpav
  18. f.Call f.Download_Feeds f.Lcd f.Share f.Vpn
  19. f.Connection f.Freeplug f.Nat f.Storage f.Vpn_Client
  20. f.Contacts f.Fs f.Network_Share f.Switch f.Wifi
  21. f.Dhcp f.Ftp f.Parental f.System f.mksession(
  22. f.Download f.Igd f.Pvr f.Upload f.register(
  23. >>> f.Freeplug.<TAB>
  24. f.Freeplug.Get_a_particular_Freeplug_information(
  25. f.Freeplug.Reset_a_Freeplug(
  26. f.Freeplug.Get_the_current_Freeplugs_networks(
  27. # Register application to get app token. Physical access is required.
  28. >>> token = f.register("AppId", "My App", "PC")
  29. # Generate session token
  30. >>> f.mksession(app_id="AppId", token=token)
  31. >>> help(f.Lan.Update_the_current_Lan_configuration)
  32. Help on method Update_the_current_Lan_configuration:
  33. Update_the_current_Lan_configuration(post_data) method of pyfbx.client.Lan instance
  34. Update the current Lan configuration
  35. Url parameters:
  36. Post data:PostData
  37. >>> help(f.Contacts.Access_a_given_contact_entry)
  38. Help on method Access_a_given_contact_entry:
  39. Access_a_given_contact_entry(id) method of pyfbx.client.Contacts instance
  40. Access a given contact entry
  41. Url parameters: id
  42. Post data:
  43. >>> f.Lan.Get_the_current_Lan_configuration()
  44. {'name_dns': 'freebox-server', 'name': 'Freebox Server', 'name_mdns': 'Freebox-Server',
  45. 'mode': 'router', 'name_netbios': 'Freebox_Server', 'ip': '192.168.1.254'}
  46. # Any subsequent call to mksession will refresh the session token
  47. >>> f.mksession()
  48. ```
  49. ## Script
  50. The included script can perform a lot of tasks.
  51. ### Basics
  52. ```shell
  53. $ pyfbx -h
  54. usage: pyfbx [-h] [-a APP_ID] [-t TOKEN] [-v] [-n] [-j] [-d DELAY] [-u URL]
  55. [-s SEND] [-c COMMAND]
  56. optional arguments:
  57. -h, --help show this help message and exit
  58. -a APP_ID, --app_id APP_ID
  59. application identifier
  60. -t TOKEN, --token TOKEN
  61. token (or f:<filename>)
  62. -v, --verbose increase verbosity to INFO, use twice for DEBUG
  63. -n, --http disable MDNS and use http known address
  64. -j, --json json output
  65. -d DELAY, --delay DELAY
  66. cylically send command (number of seconds)
  67. -u URL, --url URL specific url to query
  68. -s SEND, --send SEND url to send json to
  69. -c COMMAND, --command COMMAND
  70. command, defaults to
  71. System.Get_the_current_system_info()
  72. ```
  73. First, register the application:
  74. ```shell
  75. $ pyfbx -a SuperAppId
  76. ```
  77. Once registration is done on the device, write down the application token.
  78. You can also create a file with token as first line and application Id as second.
  79. Using this app token, acquire a session token to execute a test command.
  80. ```shell
  81. $ pyfbx -t '<TOKEN>' -a SuperAppId
  82. $ cat token.txt
  83. 2OUDy4hhM/KLQ7ru+70gfi83h5A4DUoOpDztOfqM4c2wuUiWJ+gXTHB1SbxHAFP7
  84. SuperAppId
  85. $ pyfbx -t f:token.txt -c 'Connection.Get_the_current_Connection_status()'
  86. { 'bandwidth_down': 1000000000,
  87. [..]
  88. 'state': 'up',
  89. 'type': 'ethernet'}
  90. ```
  91. _Note_ : Don't forget to escape token and command with quotes.
  92. ### Advanced
  93. You can run any commands on the freebox and retrieve complete result or single value
  94. ```shell
  95. $ pyfbx -t f:/home/foo/token.txt SuperAppId -c 'Contacts.Create_a_contact(\
  96. post_data={"display_name": "Sandy Kilo", "first_name": "Sandy", "last_name":"Kilo"})'
  97. { 'birthday': '',
  98. [..]
  99. 'photo_url': ''}
  100. $ pyfbx -u https://0s2efr3i.fbxos.fr:15628 -c "Connection.Get_the_current_Connection_status()['rate_up']" -t f:token.txt
  101. 1700
  102. ```
  103. With the delay option, commands can be sent cyclically:
  104. ```shell
  105. $ pyfbx -d 1 -c "Connection.Get_the_current_Connection_status()['rate_up']" -t f:token.txt
  106. 42460
  107. 50710
  108. 53400
  109. ```
  110. With the send option, result can be sent to a remote URL.
  111. In the following, the result is sent cyclically to example.com in json format.
  112. ```shell
  113. pyfbx -j -s http://example.com/values -d 10 -c "Connection.Get_the_current_Connection_status()" -t f:token.txt
  114. ```
  115. It's possible to execute several commands.
  116. Here, two commands are sent cyclically and results sent to an URL.
  117. ```shell
  118. 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
  119. ```
  120. Telegraf http listener v2 input plugin with json format can be used to plot data in realtime.
  121. ### Telegraf and Graphana plots
  122. You can use a telegraph configuration in /etc/telegraf/telegraf.d/freebox:
  123. ```
  124. [[inputs.http_listener_v2]]
  125. service_address = ":8182"
  126. path = "/telegraf"
  127. methods = ["POST"]
  128. read_timeout = "10s"
  129. write_timeout = "10s"
  130. max_body_size = "5KB"
  131. data_format = "json"
  132. name_override = "pyfbx"
  133. ```
  134. ![Grafana](https://framagit.org/uploads/-/system/temp/7b198d06e9c27996b60708d470af96ae/debit.png "Grafana Dashboard")
  135. ## Developpment
  136. ### Testing
  137. You can run tests with
  138. ```shell
  139. pip3 install -r requirements-dev.txt
  140. pytest tests
  141. ```
  142. The library mechanisms are tested. To get 100% coverage, a Freebox on its default IP (192.168.1.254) is required.
  143. The API description is generated and thus not functionnaly tested.