Table of Contents

Interface Details

If you haven't already please have a read though the Getting Started with the Interface article. This article concerns advanced interface issues and error trapping and responses.

How Connections to Devices are Managed

All low level interface communication is handled by background helper apps and the data sent back and forth to XTension over a TCP port. If you're getting warnings from a firewall or are running the firewall and are unable to connect to devices you may have to allow local connections to port 20300.

The background helper apps allow a much greater reliability for Xtension itself. If a USB port is disconnected any program connected to it will likely crash. If the background helper app crashes or hangs due to physical or USB connection issues XTension just restarts it a few seconds later, reopens the connection and keeps going.

Default Error Condition Handler

If the condition isn't immediately resolved and the new background process isn't able to reacquire the device it will just quit and keep retrying. The default retry count is 10 times. If after 10 retries the interface still isn't able to be opened the interface will be closed and the “Interface Error Script” will be run so you can respond in whatever way is appropriate to the problem. If you wish to increase the default retry count for an interface you can do so via applescript. In XTensions command line window enter:

set Retries of xInterface "name of your interface" to 999

that setting is saved in the database for the interface and it is not necessary that you issue it each restart or anything like that.

The Interface Error Script

If any interface encounters a problem from which it cannot recover, or when the retry count for connecting is exceeded the interface error script is run. If you wish to handle these errors yourself you need to create a Global Script named “Interface Error Script”. You can use the system script name popup menu to select it to make sure it's spelled properly in the Enter Name dialog when creating a new Global Script. Since all interfaces call the same script the “ThisInterface” value is set in the script to the name of the interface that is calling it. You may wish to send an email or other alert, switch to a backup interface, or simply re-enable the interface to keep trying.

This example logs the name of the offending interface and restarts it's connection process:

  write log "connection failure for interface: " & ThisInterface
 
  -- by re-emabling the interface we start over it's retry count.
  set enabled of xInterface ThisInterface to true

Special RFX Error handling

If you have an RFX receiver and the “exotic” data plugin you can receive Oregon Scientific and many other devices data. You may also want to manually parse packets from devices we dont directly support or you may wish to suppress error messages from bad packets.

Any unknown or unparsable packets are first sent to a handler in the Interface Error Script for you to do with as you please. If you return true from the handler then any errors are suppressed and XTension will assume you found what you wanted in there and handled it. If you return false, or there is no handler then the errors are processed like any other bad packet.

The “UnknownPacket” handler takes this form and should be put into the Interface Error Script.

on UnknownPacket( TheDataAsText, TheDataAsAListOfbytes)
  --do whatever handling you need to
 
  --and dont log a buch of debug info
  return true
end UnknownPacket

The data is passed twice, once as a string and once as a list of numbers corresponding to the value of each byte that was received. AppleScript is pretty good at dealing with strings, but internally they are all now represented by 4 byte unicode characters, so when dealing with binary data as you might get from this it may be useful to have the data already converted to bytes to avoid any text encoding issues.