xrftool(1) xrftool(1) NAME xrftool - Ciseco XRF utility SYNOPSIS xrftool [-?] [-8] [-a] [-b baudrate] [-d level] [-D] [-e escapechar] [-h] [-i inputfile] [-I] [-l logfile] [-t] [-u imgfile] [-v imgfile] device DESCRIPTION xrftool is an interactive command line utility to interact with the Ciseco XRF devices. The utility connects to the serial port and commu- nicates with the XRF device and provides command line user interaction with the device. The utility performs a number of different functions as follows: * Interactive command line mode supporting AT, LLAP and Bootloader XRF modes for command entry. * Upgrade and verification of XRF firmware. * Daemon mode to log traffic on the network with timestamps. * Wake up facilities to manage waking up sleeping LLAP devices. ARGUMENTS -h/-? Display brief help information on the utility command line. -I Display version information on the xrftool utility. -8 Output unprintable characters in octal character representation i.e. \177. The default when omitted is hexadecimal notation i.e. \xA5. -a Open existing log file and append. This option valid with the logging option -l. -b baudrate Specify the baud rate of the serial device as an integer. The default when omitted is 9600. -d level Turn on debugging level is an integer in the range 1 to 9, where 9 is the most verbose. This is reserved for development and is not normally used. -D Run in daemon mode, this is typically used to perform logging of the XRF network. In daemon mode then interactive control is dis- abled and stdout is written to /dev/null. In daemon mode then logging is typically enabled (-l) with the timestamp (-t). -e escapechar Define the XRF escape character, by default this is the plus sign '+'. If the XRF escape character has been modifed then this option should be used to inform the utility which character to use. The XRF escape character is required so that AT command mode may be invoked. -i inputFile Load an XRF image file into the utility. The image file is loaded and may be used within the XRF bootloader to verify or update the XRF firmware with the :verify or :update commands, respectively. -l logfile Output the XRF traffic to a file logfile, by default the log file is created and any existing file is over written. The append option -a causes the logging file to be opened in append mode whereby the existing file content is retained and any new content is appended to the end of the file. -t Timestamps the logging file with a date and time. i.e. 2014-12-07 19:32:50 -> aTKAWAKE---- 2014-12-07 19:32:50 -> aTKBATT2.98- 2014-12-07 19:32:50 -> aTKSLEEPING- 2014-12-07 19:37:09 -> aTLTMPA21.77 2014-12-07 19:37:26 -> aTOTMPA4.548 -u imgfile Upgrade the XRF firmware with the image in file imgfile. The firmware of the XRF is upgraded. The progression of the upload is shown on the console. The utility exits once upload is com- plete. -v imgfile Verify the XRF firmware with the image in file imgfile. The firmware of the XRF is checked against the imgfile. The progres- sion of the verification is shown on the console. The utility exits once verification is complete. device The device is the name of the device to attach to. A default device is configured into the executable images as follows: Raspberry Pi defaults to /dev/ttyAMA0 Solaris/OpenIndiana defaults to /dev/cua/0 Apple Mac defaults to /dev/cu.usbmodem000001 USE xrftool is a command line utility and in an interactive mode provides a simple command line interface to interact with the XRF. The command line operates in different context sensitive modes depending on the operating mode of the XRF as follows: :llap - The default mode, send and receive LLAP commands. :at - AT command mode, keeps the AT session open :boot - Bootloader, low level interaction with the device. :text - Text mode, for sending/receiving text between XRFs. :raw - Raw mode does not interpret the user input. The currently selected operating mode is shown at the prompt: Use ":help" for help information and ":quit" or Control-C to exit. llap-> aTOTMPA3.925 llap>> Data received from the XRF is annotated as '->', data sent to the XRF is annotated as '<-'. In all modes then the command is entered interactively by the user on the command line. The command is sent to the XRF when the ENTER or RETURN key is pressed. In AT and LLAP then command entry is case insen- sitive, the utility will automatically correct the input character case and output the command with the correct line ending as required by the operating mode. On the command line then the escape character is backslash '\'. The escape character may be used to enter non-printing characters as fol- lows: \\ - A single backslash \r - Carriage return (CR) \n - Newline (NL) \t - Tab character \xhh - Hexadecimal character i.e. \xA5 \ooo - Octal character i.e. \177. The utility may be exited at any time using the :quit command or by sending Control-C (pressing the control and 'C' key at the same time). CONTROL COMMANDS Control commands provide high level functions of the utility. The con- trol commands commence with a colon character ':' and are entered at the start of the line. The commands are defined as follows: :at Enter AT command mode Change to the AT command mode to interrogate and modify the XRF settings. On invoking the command then the guard character sequence +++ is sent to the XRF to enter AT command mode. If the request is successful then the AT command mode session is kept alive by sending a keep alive signal of "AT" which allows a com- mand line interactive session with the XRF without it timing out. Invoking the command sometimes fails and the command may be re- issued to try again. If the XRF does time out the command then the user is returned to the previous operating mode. Whilst the AT command line is active then the command prompt is shown as "at >>". Commands may be entered in upper or lower case, the command is sent to the XRF when the ENTER or RETURN key is pressed and a CR is automatically appended to the com- mand. Configuration changes are not automatically written, the user must issue a ATAC to apply any changes, exiting AT mode any other way will not commit any modifications. :boot Enter the bootloader Move to the bootloader to initiate a manual upload or write. On invoking the command then the system moves to AT mode and then issues a ATPG command to enter program download mode followed by the tilde '~' character. Invoking the command sometimes fails and the command may be re- issued to try again. If the XRF does time out the command then the user is returned to the previous operating mode. Whilst in the bootloader then the command prompt is shown as "boot>>". Commands are not modified by the system in boot mode and the command is sent to the XRF when the ENTER or RETURN key is pressed. The bootloader protocol is defined as follows: Y - Request version, the XRF should respond with 3. S - Request subversion, the XRF should respond with d. X - Exit the bootloader and will restart the devce. In boot mode then the following commands are modified: :upload - Initiate a firmware upload with any loaded image. :verify - Verify the firmware against any loaded image. :list - Lists the available bootloader commands. :find Find the current XRF state The :find command may be used to determine the current opera- tional mode of the XRF. The XRF is normally in a send and receive mode. AT command mode normally times out unless :at mode is running and artificially keeping the command mode running. If the XRF is in a strange mode then it might be stuck in the boot loader. The :find command detects this state and confirms that the bootloader is running moving to bootloader mode indicated by the prompt "boot>>". :find interrogates the system using AT mode and the bootloader version information and sometimes fails, the command can be safely run again. :help [topic] Help information Displays generic help information with no argument. The command may be invoked with a single argument topic which provides some help on the named topic. Detailed help topics included include the following: :help atbd - Help on the AT Command ATBD. :help relay - Help on LLAP Command RELAY. :help :at - Help on the control or colon commands :h may be used as an alternative to :help. :info [all] XRF information This command interrogates the XRF and displays the configuration settings of the device on the screen. With no arguments then :info displays the most important information. The command may be optionally supplied with the single argument 'all' which displays all of the configuration information e.g. :info all Produces a list of all of the XRF configuration settings i.e. info: XRF information ATVR - Firmware Versn = 0.90B XRF ATMY - Node ID Remote = -- ATID - PAN ID = 5AA5 [23205] ATEA - Encryption Txt = \xD5\x04\xCBZ\x82\xEEp\x8D\xA0... ATEK - Encryption Hex = 000102030405060708090A0B0C0D0E0F ATEE - Encrypt on/off = 0 etc. Characters which cannot be displayed are shown in hexadecimal with the nomenclature \xHH. Hexadecimal fields are are shown with their decimal equivalents in square brackets. :info enters AT mode to retrieve the information and then exits when it finishes. Sometimes the command fails to enter AT mode, the command should be repeated. :llap Enter LLAP mode Change the input mode to LLAP for sending and receiving LLAP commands. Whilstthe LLAP command line is active then the com- mand prompt is shown as "llap>>". In LLAP entry mode then LLAP commands may be entered in upper or lowercase and are translated into the appropriate case and command endings are automatically padded with '-' to the correct length before being dispatched. The command is sent to the XRF when the ENTER or RETURN key is pressed. In LLAP mode then no automatic line ending is added to the command. See also :wake which allows a wake-up to be scheduled against a sleeping LLAP device. :list [topic] List the commands available This command lists the available commands. Without arguments then the command list presented is context sensitive as follows: at >> - In AT mode then list the AT commands. llap>> - In LLAP mode then list the LLAP commands. boot>> - In the bootloader then list the boot commands. raw >> - In any other mode the control/colon commands are listed The list command may be given an optional argument topic which identifies the list of commands required. i.e. :list llap The following mode names are recognised: at - List the AT commands. boot - List the bootloader commands. llap - List the LLAP commands. commands - List the colon commands class - List the LLAP device classes. device - List the LLAP device classes. The commands recognised by the individual LLAP device classes may also be listed i.e. analog - List Analog sensor LLAP commands base - Base commands button - List Button & Hall Effect device LLAP commands dallas - List Dallas temperature sensor decice LLAP commands gio - List Generic I/O device LLAP commands light - List Light Dependant Resistor (LDR) LLAP commands relay - List Dual Relay LLAP commands therm - List Thermistor Temperature LLAP commands :quit Quit/exit utility The :q or :quit command exits the utility. :raw Raw input mode, messages sent with no conversion Change the input mode to raw which allows for character entry which is not translated to mode specific content. i.e. every- thing that is entered by the user is sent literally. Whilst raw mode is active the command prompt is shown as "raw >>". On the command line then the escape character is a backslash '\'. The escape character may be used to enter non- printing characters. The command is sent to the XRF when the ENTER or RETURN key is pressed. In raw mode then no automatic line ending is added to the command. :text Enter TEXT mode, messages sent with CR+LF Change the input mode to text mode. This allows free text entry and automatically appends a CR+NL when the command is sent. Text mode may be used to send text messages when the XRF is operating like a serial console i.e. communicating between two XRF devices. Whilst text mode is active the command prompt is shown as "text>>". The command is sent to the XRF when the ENTER or RETURN key is pressed. In raw mode then the CR+NL (\r\n) line ending is added to the command when it is sent. :upload Upload firmware to XRF This command may only be used while in the bootloader "boot>>". The command performs a firmware write operation with the cur- rently loaded firmware image. The firmware image is loaded from the command line with the -i option. Once the upload has completed then XRF is reset and the user is restored to the previous operating mode. :verify Verify firmware in XRF This command may only be used while in the bootloader "boot>>". The command performs a firmware verify operation with the cur- rently loaded firmware image. The firmware image is loaded from the command line with the -i option. Once the verification has completed then XRF is reset and the user is restored to the previous operating mode. The verify will fail if the image does not match the XRF firmware. :wake [id [lappcmd llapcmd ....]] Wake LLAP device from sleep This command is used to schedule commands to be sent to a LLAP device when it wakes up. Whilst the utility is running then the LLAP responses are monitored and if aXXAWAKE----, aXXBATT2.47-, aTABATTLOW-- or aXXSTARTED-- command is seen then the commands scheduled for device id XX are executed. The optional argments are defined as follows: id The 2 character device identity to wake up. llapcmd A space separated list of LLAP commands. Each command on the line is executed in turn. The commands may be entered in upper or lower case and their endings are automati- cally padded with '-' to the correct length. When the :wake command is issued it is scheduled immediately and remains active in the background until the device awakens. AT mode should not be entered when a wake is scheduled as this blocks the serial reception of the XRF. e.g. :wake TX aTXINTVL10M aTXCYCLE This example waits for device TX to awaken, changes the sleep interval to 10 minutes and then puts the device back to sleep. If a device is rebooted i.e. changing device ID then two :wake commands are required one for the AWAKE which does the reboot, and one for the STARTED to put the device back to sleep. :wake TX aTXCHDEVIDYZ aTXREBOOT :wake YZ aYZINTVL10M aYZCYCLE The :wake command with no arguments lists the LLAP devices that are scheduled to wake up. An example session is shown below: :wake TX aTXCHDEVIDYZ aTXREBOOT Wake TX [wait] aTXCHDEVIDYZ aTXREBOOT--- Wake installed OK. :wake YZ aYZINTVL10M aYZCYCLE Wake YZ [wait] aYZINTVL10M aYZCYCLE---- Wake installed OK. :wake Wake YZ [wait] aYZINTVL10M aYZCYCLE---- Wake TX [wait] aTXCHDEVIDYZ aTXREBOOT--- 2 wake counter(s). llap>> :wake operates by monitoring for an AWAKE or BATT command from the device with a matching ID. When the command is seen on the network then a aTAWAKE----- followed by a aXXHELLO---- command is sent to the device, and the wake becomes active. The device, if awake, will respond with a aXXHELLO----. Receipt of the HELLO from the device is used as a confirmation that the device is awake and the commands associated with the :wake are sent to the device. Similarly on STARTED event, a HELLO is exchanged with the device to confirm it is ready to receive data before commands associ- ated with the :wake are sent to the device. For coin battery operated devices then it is important to send the devices back to sleep as soon as possible in order to con- serve power. This must be performed on the :wake command list otherwise the device will remain awake and draw power. The util- ity does not automatically put any woken device back to sleep again. EXAMPLES Some examples of command line interaction with xrftool. Running the tool interactively For normal running then no command line argument is generally required unless the device is running on a different port or baud rate i.e. a non-stadard device with a different baud rate may be invoked as follows: xrftool -b 19200 /dev/cua/4 Upgrading firmware To upgrade the firmware then the Ciseco image file should be downloaded onto the local machine. There are no issues with the line endings and may be UNIX or Windows line endings, there is no need to convert the file. A typical upgrade command line is as follows: xrftool -u /.../llapThermistor-V0.73-24MHz.bin This upgrades the XRF firmware with the LLAP Thermistor person- ality. The firmware image may include a absolute or relative pathname. Running in daemon mode When new systems are installed it is useful to be able to col- lect temperature and other information from a running system over a longer period of time. The tool may be run in daemon mode in the background as follows: nohup xrftool -a -l ciseco.log -t -D & This uses the nohup(1) command to ensure that the command is not stopped when the terminial is closed. nohup runs xrftool in dea- mon mode (-D) with logging (-l) and timestamp (-t) enabled. The logging file is appended (-a) to the existing file ciseco.log. BUGS xrftool reconfigures the terminal IO to handle interactive input and handles signals to manage a clean exit enabling the terminal to be restored to its previous operational state. In instances where the utility does not exit cleanly then it can leave the terminal in a bad state. The terminal may be restored to a correct working state using the command stty sane. Refer to stty(1) for more information. BACKGROUND This utility was written after being frustated with the existing lack of tools for the Rasperry Pi. The intention is to make the loading and user interaction for management functions with the Ciseco XRF personal- ities a little easier on the Raspberry Pi. COPYRIGHT Copyright (c) 2014 Jon Green NO WARRENTY This program is licensed free of charge, there is no warranty for the program, to the extent permitted by applicable law. Except when other- wise stated in writing the copyright holders and/or other parties pro- vide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary ser- vicing, repair or correction. In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the program as permitted above, be liable to you for dam- ages, including any general, special, incidental or consequential dam- ages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages. SEE ALSO nohup(1), minicom(1), stty(1). 2014 December 09 xrftool(1)