plugins:rawprotocol
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
plugins:rawprotocol [2018/05/22 16:35] James Sentman |
plugins:rawprotocol [2018/08/11 15:31] (current) James Sentman |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====Raw Protocol Docs APIv2==== | ====Raw Protocol Docs APIv2==== | ||
| XTension talks to it’s plugins via a socket connection. Currently most plugins run on the same machine as XTension but there is support for allowing the plugins to connect from external machines as well. If you’re writing your plugin in Python or other future supported scripting systems then all this work will be taken care of by the XTension object that is provided by the included scripts. This information is provided for those that might wish to implement a connection from an unsupported scripting system or a binary compiled application. Note that at this moment all communication at this level with XTension is unencrypted. No SSL support is available for this channel. The reason being that most or all of the communication at this level is between apps running on the same machine and so encrypting it doesn’t make any sense. If remote connections are necessary over the internet I would recommend using a VPN or other encrypted channel to forward the data such as an SSH tunnel. | XTension talks to it’s plugins via a socket connection. Currently most plugins run on the same machine as XTension but there is support for allowing the plugins to connect from external machines as well. If you’re writing your plugin in Python or other future supported scripting systems then all this work will be taken care of by the XTension object that is provided by the included scripts. This information is provided for those that might wish to implement a connection from an unsupported scripting system or a binary compiled application. Note that at this moment all communication at this level with XTension is unencrypted. No SSL support is available for this channel. The reason being that most or all of the communication at this level is between apps running on the same machine and so encrypting it doesn’t make any sense. If remote connections are necessary over the internet I would recommend using a VPN or other encrypted channel to forward the data such as an SSH tunnel. | ||
| + | |||
| + | ===Supported Languages=== | ||
| + | At this moment the only examples are for connecting with Python. Since the connection to XTension is through a socket and the protocols are documented any language capable of implementing these protocols would work just fine though you might have to implemented these protocols yourself. I currently have release level plugin implementations in Python and [[http://xojo.com/|Xojo]], I also have an alpha level implementation written in Node JS for Javascript. That is a problem in releasing a plugin as you would either have to embed the NodeJS interpreter into your plugin or require that the user install it and it’s other dependencies before installing your plugin. At this moment I don’t recommend using that though there are other possibilities in the future for how I might handle javascript plugins. | ||
| + | |||
| + | A Xojo plugin is an excellent option if you require a binary application. The downsides are that the application is larger but otherwise those plugin libraries are well debugged as I use them myself quite a bit. | ||
| + | |||
| + | Another option is to wrap a command line utility in some simple python code rather than start from scratch. If the command line utility is not already installed on MacOS and licensing permits it you can include the binary utility in the plugin itself so that no other installations are necessary. This is the tack I took with the [[supported_hardware:switchbot|Switchbot]] plugin. Since controlling BluetoothLE would have required new python libraries be included and I wanted to provide a command line utility for it anyway I wrote the low level bluetooth handlers into a command line utility and included it inside some relatively simple Python code. You can examine the code as an example by downloading the switchbot plugin linked to above. | ||
| ===What is a plugin=== | ===What is a plugin=== | ||
| Line 152: | Line 159: | ||
| |xtKeyValue|(string representation of the new numerical value)| Required for a set value command. XTension can hold float number values for Units so it’s fine to send 17.5 or just 0 or -400 or whatever makes sense for this unit| | |xtKeyValue|(string representation of the new numerical value)| Required for a set value command. XTension can hold float number values for Units so it’s fine to send 17.5 or just 0 or -400 or whatever makes sense for this unit| | ||
| |xtKeyUpdateOnly|(boolean)|optional. If you include this value and it’s set to True then the unit will only update itself if the new value is different from it’s current value. If this is absent or set to false then any value will cause the Unit to update, run it’s unit scripts and update it’s Last Activity date. This is useful for things like temperature sensors that might repeat their values fairly often without changing. By setting this flag to true you can send each reading to XTension but not have it spam the log with new values unless something changes. Even if the Unit Scripts do not run the last message received date (not the Last Activity date) will be updated. This can be used to display errors for sensors that stopped responding if you know you can expect a message from them fairly often. So it’s generally a good idea to send updates as often as they come in but with this flag set to true.| | |xtKeyUpdateOnly|(boolean)|optional. If you include this value and it’s set to True then the unit will only update itself if the new value is different from it’s current value. If this is absent or set to false then any value will cause the Unit to update, run it’s unit scripts and update it’s Last Activity date. This is useful for things like temperature sensors that might repeat their values fairly often without changing. By setting this flag to true you can send each reading to XTension but not have it spam the log with new values unless something changes. Even if the Unit Scripts do not run the last message received date (not the Last Activity date) will be updated. This can be used to display errors for sensors that stopped responding if you know you can expect a message from them fairly often. So it’s generally a good idea to send updates as often as they come in but with this flag set to true.| | ||
| - | |||
plugins/rawprotocol.1527006945.txt.gz · Last modified: 2018/05/22 16:35 by James Sentman
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
