supported_hardware:diy
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
supported_hardware:diy [2017/04/16 18:00] – external edit 127.0.0.1 | supported_hardware:diy [2023/02/13 14:52] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
=====Do It Yourself===== | =====Do It Yourself===== | ||
- | If you want to add some device that XTension doesn' | ||
- | This method lets you connect to a native serial port, or a [[: | + | **This page is about the new DIY plugin which replaced the original DIY plugin in XTension 9.4.31.** The original plugin is deprecated and will be removed completely in a current version. Please try your DIY interfaces with the new plugin and let me know if there are any issues. See the section below on converting from the legacy DIY plugin, there are some minor differences in the initial setup and configuration. The legacy plugins original documentation has been moved [[diylegacy|here]], |
- | In general, what we do is to create an ' | + | The DIY plugin provides a way to easily connect to a device that does not have a specific plugin yet. The DIY plugin will provide a pipe to either a TCP socket on a remote device or a serial port connected directly |
- | For example, I have a very old serial port multiplexer | + | ====XTension Setup: |
+ | To create | ||
- | Here I'll show how to create the port, send data from one iMac to the other, receive | + | {{: |
+ | **Port Selection: | ||
- | Let's create | + | **Serial Ports:** If you select a serial port you need to setup the necessary properties of the port such as baud and handshaking that might be necessary here. Most devices will connect at whatever baud it is built for but with the default other settings |
- | In the XTension FILE menu, choose Preferences, | + | |
- | Then choose NEW... | + | |
- | {{: | + | |
- | Notice | + | There is a very old specification |
- | | + | |
- | Notice also that if you choose | + | |
- | Now, you will want to set up the scripts for this DIY interface. | + | The **Turnon RTS** and **Turnon DTR** checkboxes |
- | {{: | + | |
- | + | ||
- | Notice that there are two ' | + | |
- | XTension provides | + | The Baud popup contains the standard list of baud rates that most or all USB/Serial adaptors support. It is possible to open the port with a non-standard baud rate if your USB/Serial adaptor supports this. At the moment there is no interface in XTension to setting |
- | {{: | + | |
- | You can use these verbs anytime, but it's the most logical | + | If you need to send a “Break” |
- | The **on DataAvailable()** handler | + | It is possible to read the state of the RI and CD line from the serial adaptor. At the moment there is no support for this in the plugin. If this is something you need to do please drop me an email and I will add supporting it to the list. |
- | Here you put all the code that knows what to do when data is received from your device. \\ | + | If the underlying hardware supports it it may be possible to properly talk to and configure an RS485 connection. As of this release there is no support for this in the plugin. If it is something that would be useful to you I can move the supporting of it up the priorities list. Please let me know. If you simply need an RS485 connection for something most USB/485 adaptors will handle most of the settings by default |
- | In this example, I simply write whatever I receive | + | **TCP Connections: |
- | Now, on the iMac named Perelandra, which is also connected | + | If you are connecting |
- | {{: | ||
- | This handler will also write the received | + | ====Parsing Options==== |
+ | Parsing a data stream can be difficult and fraught with danger, especially if you are attempting | ||
- | **Update** there are now 2 different onDataAvailable events | + | If you are connecting to a true serial port the port will be flushed after opening so you should not receive a potentially large chunk of truncated garbage from the port buffers. This cannot be done for a TCP connection |
- | < | + | **NOTE** in the original DIY plugin these settings were not available in the initial plugin configuration and required that you use the [[dictionary: |
- | on dataAvailable( theDataAsString, theDataAsBytes) | + | |
- | </ | + | |
- | you can process | + | ===Send |
+ | This would be the default selection. At any seemingly random time while receiving data the system may choose | ||
- | When talking to something that uses a binary protocol | + | ===Fixed length packets: |
+ | If your device always sends the same length of packet you can use the fixed length packet parser. The port is opened | ||
+ | |||
+ | ===Wait for more data until:=== | ||
+ | The port is opened | ||
+ | |||
+ | ===Split data on terminator=== | ||
+ | This is arguably the most useful of the parsing options. Many simple ascii protocols will terminate each packet with a carriage return or newline character or something similar. At this moment you can enter any simple character string into the field and include this short list of special characters: | ||
+ | |||
+ | |\n|Carriage Return| | ||
+ | |\r|New Line| | ||
+ | |\t|Tab| | ||
+ | |\0|Null Character| | ||
+ | |||
+ | So to split on a carriage return line feed pair you would enter “\r\n” into the terminator field. | ||
+ | |||
+ | If you need other special characters or can imagine other ways that pre-parsing could be improved | ||
+ | |||
+ | At any point you can call the [[dictionary: | ||
+ | |||
+ | |||
+ | ====Receiving Data:==== | ||
+ | |||
+ | To create the script that will receive the data received and parsed by the plugin | ||
+ | |||
+ | There are 2 different formats of the **DataAvailable** | ||
+ | |||
+ | In AppleScript the handler would look like: | ||
< | < | ||
- | on binaryDataAvailable( theDataAsBytes) | + | on dataAvailable( theDataAsString, |
+ | write log “DIY Interface Received: “ & theDataAsString | ||
+ | end dataAvailable | ||
</ | </ | ||
- | any data including nulls or binary 0’s can be used in applescript via this handler. Both handler are available in the template script that is loaded when you first create | + | This handler |
+ | If you are dealing with binary data then it may not be possible for AppleScript to send you the data as a string in the above example. If that is the case then you’ll see an error in the XTension log such as “unable to make data into specified type” or something similar whenever the plugin is trying to execute the Data Available event. If this happens then you need to use instead the **binaryDataAvailable** which does not attempt to turn the binary data into a text string but will instead only pass you an AppleScript list of bytes as individual numbers. | ||
+ | < | ||
+ | on binaryDataAvailable( theDataAsBytes) | ||
- | Now, to start this all off, we're going to use the XTension verb **" | + | set s to “received “ & length |
- | {{: | + | |
+ | repeat with thisNumber in theDataAsBytes | ||
+ | set s to s & (thisNumber as text) & “ " | ||
+ | end repeat | ||
+ | | ||
+ | write log s | ||
+ | end binaryDataAvailable | ||
+ | </ | ||
- | which will be passed thru **the PIPE**, to the iMac " | ||
- | {{: | ||
+ | ====Sending Data==== | ||
+ | Sending data to the port is accomplished with the [[dictionary: | ||
- | The handler will then see that there is the keyword " | + | If you are sending the data from inside the Interface script |
- | Which will be passed to the **DataAvailable** handler on " | ||
- | {{: | ||
- | Oh yes, don't be confused by that first line in the above snippet...that is just what XTension displays in response to the **send data** command ... it's a text representation of the HexaDecimal value sent to the DIY interface. If you don't understand ' | ||
- | Now I've probably made this example too complex by showing two copies of XTension, but this is something | + | ====Working with Binary Data==== |
+ | Working with binary data in AppleScript is difficult. | ||
+ | [[dictionary:bitwise|]] portion | ||
- | The [[dictionary: | ||
- | |||
- | Update: | ||
====Sending commands from units==== | ====Sending commands from units==== | ||
Line 108: | Line 133: | ||
The value of the unit in the database is not updated until after these handlers return. | The value of the unit in the database is not updated until after these handlers return. | ||
+ | |||
+ | |||
+ | ====Additional Scripting Commands==== | ||
+ | In addition to the [[dictionary: | ||
+ | |||
+ | |||
+ | ===Send Break=== | ||
+ | For some serial devices it may be necessary to send a “break” A break on the serial port was used by some devices as a synchronization method or a way to reset a conversation. It is still part of the DMX protocol. A break is really just a longer than appropriate holding of the data line at the mark voltage, the interface interprets this as a breaking of the standard data flow and it can be read by the controller and passed on to the software. You use the **SendBreak** command along with a floating point number of the number or fraction of seconds you wish to hold the port in this break state. The plugin will pause while the port is in the break state and not attempt to send any more data until it has expired. You do not have to add delay or pause statements to account for it. | ||
+ | |||
+ | To send a 500ms break you would use something like: | ||
+ | |||
+ | < | ||
+ | tell xInterface “name of the DIY interface” to sendBreak( 0.5) | ||
+ | </ | ||
+ | |||
+ | Or if inside the Interface’s script you could use the (thisInterface) value like: | ||
+ | |||
+ | < | ||
+ | tell xInterface (thisInterface) to sendBreak( 0.5) | ||
+ | </ | ||
+ | |||
+ | ===SetRTS=== | ||
+ | Pass a boolean to the command to set or clear the RTS pin on the fly. The initial state of this should be set in the Edit Interface dialog but you can change change it after the fact using this command. If the device requires handshaking and you have that turned on and are not trying to manage it yourself you may break that by calling this, or depending on the serial interface it may refuse to actually make any changes at all. This is probably most useful when handshaking is set to none or xonxoff. | ||
+ | |||
+ | < | ||
+ | tell xInterface “name of interface” to setRTS( true) | ||
+ | tell xInterface “name of interface” to setRTS( false) | ||
+ | </ | ||
+ | |||
+ | ===SetDTR=== | ||
+ | Identical to the above SetRTS command and with the same warnings about hardware flow control except that it controls the state of the DTR line. | ||
+ | |||
+ | < | ||
+ | tell xInterface “name of interface” to setDTR( true) | ||
+ | tell xInterface “name of interface” to setDTR( false) | ||
+ | </ | ||
+ | |||
+ | ====Converting from the Original DIY Plugin==== | ||
+ | In general the new plugin should work and handle your data identically to the old version. Please test this and let me know if there are any problems. Of all the plugins this may be the most difficult to test since there are so many wildly different use cases. | ||
+ | |||
+ | The conversion is not destructive and if you have problems you can immediately go back to the original plugin. | ||
+ | * Disable the interface in the Interfaces list window | ||
+ | * Edit the original interface. | ||
+ | * Change the selection in the popup from “DIY Scripted Interface” to “DIY Interface” which will also show a version of at least 2.0b1 in the popup. | ||
+ | * Add the proper parsing settings to the Edit Interface dialog as these can now be set at startup without needing the call to that in the init method. You can comment that call out with the new interface if you set the settings in the edit dialog. The verb is still supported however and will work as before. | ||
+ | |||
+ | If you need to revert simply change the Device popup back to the original plugin and re-enable it. | ||
+ | |||
+ | |||
+ | |||
+ | ====History: | ||
+ | * The [[supported_hardware: | ||
+ | * The initial DIY plugin was part of XTension since the early 2000s. | ||
+ | * The new API2.0 DIY plugin replaced the original in XTension version 9.4.31 in June of 2020. | ||
+ | |||
supported_hardware/diy.1492365617.txt.gz · Last modified: 2023/02/13 14:51 (external edit)