Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Info.json: Communications=====


By default XTension will provide your plugin configuration window with a popup that includes the name of all available serial ports (and any notes the user has added to them as well as a button to add a note to make it more obvious that say a device is connected to “usb12376t34765t” or something like that), an option to make an outgoing network connection and an option to accept incoming connections. The selection controls what other interface elements are displayed below it. For an outgoing connection an IP/DNS name and port field are displayed, the values of which are available to your plugin through the XTension.settings object. A default dns name and port can be provided with keys shown below. If an incoming connection is needed a field to enter the port it should run on is displayed and this info as well as it’s default can be added via keys to the info.json file. If your plugin does not require this popup at all and will provide it’s own interface to whatever initial setup is needed there is a key to set it to None and then this popup and it’s coresponding fields will be hidden.

The use of this may make it unnecessary to have to create any custom interface for your plugin at all, or at the very least should simplify it in most cases. 

These keys are optional and in their absence the entirety of the selections mentioned above will be displayed. These three keys are mutually exclusive, it makes no sense to specify more than one. To control more specifically see the allow keys below.

-----
>**portSelectNone** Boolean - Set to true to hide the entire port/connection popup. It defaults to false so it is not necessary to include it unless you wish to set it to true.
  “portSelectNone”:true,


>**portSelectOutgoing** Boolean - Set to true to hide all selections but the outgoing network connection. This will show the Address and Port fields by default and not allow the selection of a serial port or a listening connection. The default is false, you only need to include this if you need it to be true.
  “portSelectOutgoing”:true,


>**portSelectIncoming** Boolean - Set to true to hide all options other than the Server Settings for port, optionally a checkbox and fields to describe a bonjor service. This defaults to false, you only need to include it if you need it to be true.
  “portSelectIncoming”: true,


-----

It is also possible to combine the various options so that you could select from either a serial port or an outgoing or incoming network connection. This is common if you are connecting to a serial device, but want to support it connected over either a local serial port or via an ethernet serial bridge device. The XTension plugin has classes to automatically provide you with a pipe taking this into account so that you do not have to have separate code to talk to a serial port or a network port but this will not be helpful in all cases, if you wish to support this you may have to implement both connection methods in your own code. In general I support this whenever possible as moving devices to remote locations and putting them on ethernet is often much easier than running long serial lines from the XTension server.

>**allowIncoming** Boolean - Set to true to enable the Incoming TCP setting to be selected from the “port” popup or set to false to disable this selection when showing the serial ports.
  “allowIncoming”: false,


>**allowNoPortSelection** Boolean - If set to true another option will be available at the top of the port list just called “None” it will disable all other interfaces for network configuration if selected. This is what is force selected by the above key of portSelectNone. It defaults to false so you must set this if you wish the user to be able to choose None as well as other options.
  “allowNoPortSelection”: true,


>**allowSerialPort** Boolean - if set to false then no serial ports will be shown in the port popup and the choices will be limited to incoming or outgoing TCP or possibly None depending on the other options set. Defaults to true.
  “allowSerialPort”: false,


>**allowSSL** Boolean - if set to true and you select a listen for incoming connections type a “Use SSL” checkbox will be displayed along with the listening port fields. This setting will be available to your plugin via the XTension.settings object. XTension provides an interface to creating self signed ssl certs that can be used by any plugin. More information on that is forthcoming. Yes, they are self signed so you cannot verify then, but as long as you first load the keys when you are locally connected you will be able to  know if they are changed or become invalid, so you will know if someone is man in the middling you.
  “allowSSL”:true,


>**allowBonjour** Boolean - If true and you select a listen for incoming connections type an extra line of fields related to registering a bonjour, or mDNS or zeroconf or whatever they are calling it this week, will be available. This will be automatically handled by XTension if present and the info as entered will be registered. No other action is needed by the plugin. It will be registered upon enabling the plugin and de-registered upon disabling the plugin or quitting the app.
  “allowBonjour”:true,


=====Setting Default Values:=====

Default entries for dynamic plugin interfaces can be set in the interface builder app. There are keys for all the built in communication fields you can add.

>**defaultAddress** String - If an outgoing TCP connection is selected this will be placed into the address field if no previous value has been set yet for this instance.
  “defaultAddress”:”weatherslam.local”,


>**defaultPort** Integer - If an outgoing TCP connection is selected this will be placed into the port field if no previous value has been set.
  “defaultPort:22,


>**defaultBonjourName** String - If bonjour is enabled this will be placed into the service name field.
  “defaultBonjourName”:”weatherslam”,


>**defaultBonjourService** String - If bonjour is enabled this will be placed into the service type field. 
  “defaultBonjourService”:”_http._tcp.”,

=====Default Serial Port Settings:=====

If you are using the helper class to abstract communications between serial ports or outgoing TCP connections you may specify the serial port settings in the info.json file and the helper class will use these values if they are not overridden by the program later. This has no effect if the connection type is set to outgoing TCP. In that case it is up to the remote network/serial adaptor to be properly setup ahead of time. There is a protocol to handle this out there but I have yet to encounter a device that supports it that isn’t priced more than our entire systems as it is meant for industrial use. If you have a need for an implementation of this please let me know.

If you are not using the helper communications class you may still use these keys but pulling them out and setting up the serial port will be up to you.

**NOTE** these keys are not camel cased like most of the others.

>**baud** Integer - The default baud rate that the helper networking class will use when connecting to a serial port. Any standard or custom baud rate that is supported by the adaptor can be used. Not all adaptors support non-standard baud rates. There is no default baud, you must specify this if necessary.
  “baud”:14400,


>**bytesize** Integer - 5, 6, 7, or 8 bits. This defaults to 8 which is the only setting I’ve ever had to use but the others are available. Include only if needed.
  “bytesize”:8,


>**stopbits** Integer - 1 or 2, defaults to 1. Include only if needed.
  “stopbits”:1,


>**parity** Enumerated String - must be one of the following: “odd”, “even”, “mark”, “space”, “none”. Defaults to none, include only if needed.
  “parity”:”even”,


>**xonxoff** Boolean - Set to true if using xon/xoff characters for handshaking. The remote device must support this. Defaults to false.
  “xonxoff”:true,


>**rtscts** Boolean - Set to true if using the rts and cts lines for hardware flow control. Both the remote device and the serial adaptor must support this. Defaults to false.
  “rtscts”:true,


>**dsrdtr** Boolean - Set to true if using the dsr and dtr lines for hardware flow control. Both the remote device and the serial adaptor must support this. Defaults to false.
  “dsrdtr”:true,


====RTS and DTR Control:====

Some devices that provide rs232 to an internal ttl level serial, which is probably most of the devices we are talking to, will use power from the RTS or DTR line to either power the opti-isolator or to derive the voltage necessary for the various line levels. If so it may not work at all when run without these lines turned on. When not used for hardware flow control these lines can be held on by the driver and device if they support that, to power this portion of the device. If you don’t need this and are not using hardware flow control this will have no effect, if it is necessary then they will not work at all without setting it up properly.

>**rtson** Boolean - set to true to force the driver to keep the RTS line high while the port is open. Defaults to false. Include only if needed or it may cause other problems, especially if a hardware flow control is also needed.
  “rtson”:true,


>**dtron** Boolean - set to true to force the driver to keep the DTR line high while the port is open. Defaults to false. Include only if needed or it may cause other problems, especially if a hardware flow control is also needed.
  “dtron”:true,




-----
Previous: [[pluginapi:infojson]]

Next: [[pluginapi:infomisc]]