plugins:rawprotocol
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
plugins:rawprotocol [2018/05/22 16:04] James Sentman created |
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 115: | Line 122: | ||
| - | Once you can parse and flatten these 2 objects you are ready to communicate with XTension. | + | ===Getting Your Configuration=== |
| + | Once you’re connected you can ask XTension for your configuration info. This will include all the port names or internet addresses or any other data that is setup in the interface setup dialog or your dynamic interface embedded in the same. Sending this command also subscribes you to any changes in the settings xtData object in XTension. So if any value is edited by the user the new values will be sent as an update packet which you should merge with the existing xtData object thereby generating subscriber events for anyone that needs to know if those values change. | ||
| + | |||
| + | ^Key Constant^Value^ ^ | ||
| + | |xtKeyCommand|xtCommandGetKeyedData| Required. All xtCommand objects must at least have a command key specified| | ||
| + | |xtKeyAddress|”all”|Required. You can save other keyed data object into the preferences if necessary, requesting the one with the constant string “all” (without the quotes) will send you the base data and all settings on the edit interface dialog window.| | ||
| + | |||
| + | XTension will then respond with another command that will have the xtData object with all that information flattened into the command under the xtKeyData key. | ||
| + | |||
| + | Response: | ||
| + | ^Key Constant^Value^ ^ | ||
| + | |xtKeyCommand|xtCommandSetKeyedData| a reply with an xtData object stored in the xtKeyData key. Use the xtKeyAddress key to find the name of the object.| | ||
| + | |xtKeyAddress|”all”| (without the quotes)| | ||
| + | |xtKeyData| (flattened xtData information)| pass to the parse method of a new xtData object| | ||
| + | |||
| + | |||
| + | |||
| + | |||
| + | |||
| + | If you have not yet received any base configuration then unflatten the xtData as sent and store it to a global or class variable. If you have already received this data and receive this command with this address again then it will contain only the changes that have been made to the settings by the user. Unflatten the changes into a new xtData object and merge it with the existing xtData class of your settings so that any changes can be sent to subscribers interested in those values. | ||
| + | |||
| + | |||
| + | |||
| + | |||
| + | |||
| + | ===Controlling Units=== | ||
| + | For more detail see the plugin examples. To tell XTension that you have received a value change for a unit you would create an xtData object, insert the following key/value pairs, flatten the command and send it up the pipe. Note that all values stored in the xtCommand object are strings. | ||
| + | |||
| + | You can send a command to a Unit in XTension in 1 of 2 ways. A plugin that has received access to the entire database should include the unitqueID key in the command with the number set to the ID string from the Unit they want to control. A normal plugin with access only to it’s own units should include both the device type “tag” as specified in the info.json file as well as the address key. The command will be routed to and handled by the proper unit in XTension either way. | ||
| + | ^Key Constant^Value^ ^ | ||
| + | |xtKeyCommand|xtCommandSetValue| Required. Every command must always include a command key| | ||
| + | |xtKeyAddress|(any string)| Required. The same string as set in the Unit’s address field in XTension| | ||
| + | |xtKeyTag|(any string)| Required. Each device type requires a tag that tells XTension which kind of unit the command is destined for. See the info.json docs for more info.| | ||
| + | |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.| | ||
plugins/rawprotocol.1527005092.txt.gz · Last modified: 2018/05/22 16:04 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
