|
Sherlock
Consulting Limited |
Red Earth Systems I/O Modules (RESIO)
RESTalk Test Harness
Document Type |
Technical Reference - Uncontrolled |
Document Version |
1.5 |
Document Reference |
RESTalk User Guide.doc |
Date |
31 July 2005 |
Author |
Jason Watton |
Status |
Review |
Total Number of Pages |
13 |
2005 Sherlock Consulting Limited
No part of this document may be
reproduced or transmitted, in any form or by any means (electronic, mechanical,
photocopied, recorded or otherwise) or stored in any retrieval system of any
nature without the express written permission of Sherlock Consulting Limited.
Contents
1. Introduction 3
1.1 Product Overview 3
1.2 References 3
1.3 Readership 3
1.4 Acknowledgements 3
1.5 Glossary 3
2. Introduction 4
2.1 General 4
2.2 Purpose 4
2.3 Scope 4
3. System Overview 5
4. Installation 6
4.1 System Requirements 6
4.2 Components 6
4.3 Installation 6
5. User Guide 7
5.1 Byte Ordering Convention 7
5.2 Commands and Replies 7
5.3 Running RESTalk 7
5.4 Version / About RESTalk 7
5.5 The Main Dialog 8
5.6 Log 8
5.7 Module List 8
5.8 Display Options 9
5.9 Mode (latched buttons) 9
5.10 Send List 9
5.11 Sending Ad-hoc Data 9
5.12 Sending Data from the Send List 10
5.12.1 Add 10
5.12.2 Send Selected 10
5.12.3 Send All 11
5.12.4 Clear 11
5.12.5 Key shortcuts 11
5.13 Watching for Module Replies 11
5.14 Sending one or more Module Commands 11
5.15 Loopback Test 11
5.16 Multi-Message Test 12
6. Data File Formats 13
6.1 ‘tlk’ Command Files 13
6.2 ‘.tlk’ File Format 13
This document describes use of the RESTalk PC application.
RESTalk is a test harness for demonstrating and proving I/O using the Red Earth Systems range of USB I/O modules.
Ref |
Title |
Author |
Description |
API |
RESIO API Specification |
Red Earth Systems Limited |
A description of the RESIO API to the RES I/O Modules. |
This document is targeted at any person involved in using the RES I/O Modules.
This document is a first edition.
This document owes its content to:
All chapters were written by Jason Watton.
All of the above have the right to be identified as authors of the work.
Definitions in the text are shown italicized and bold. Use of terms recently defined elsewhere or a direct quote from elsewhere in the text are shown italicized. Bold and underlining are used for emphasis.
API |
Application Programmer's Interface, a set of functions and declarations which provide the programmer of an application to use an object. |
BIT |
Built-In Test |
CAN |
Controller Area Network |
Hex |
Hexadecimal |
RESIO |
Red Earth Systems I/O system - a range of simple modules for developers to control electronic I/O from a PC. |
Rx |
Receiver/Reception |
Tx |
Transmitter/Transmission |
mC |
Micro-controller. |
mP |
Microprocessor. |
USB |
Universal Serial Bus - an electrical and signaling standard plus protocol for device communications. |
RESTalk is a Microsoft Windows® application which allows direct control of multiple Red Earth Systems I/O modules using the USB interface and the RESIO API. Data may be sent and received and displayed on the screen of a PC.
This document is the User Guide for the RESTalk application.
This guide provides information about the use of the RESTalk application, its capabilities, the embedded Loopback Test, and the format of the data files it uses.
This guide has been written using version 1.5 of the RESTalk application. Subsequent minor versions (1.x) are guaranteed to be compatible.
This diagram is for Windows 2000 and Windows XP only. A Windows 98SE/Me system has a different configuration.
a) An IBM-PC compatible 386 or better with 1 USB 1.1-compatible port.
b) Windows 98SE, Windows Me, Windows 2000, or Windows XP. Note that Windows NT 4 is not sufficient.
The RESTalk application consists of 1 executable file (RESTalk.exe), a service library (RESIO.dll), plus a set of ‘.tlk’ data files defining typical transmissions. These sample data files are not required to run the application.
Command data files for transmission to the modules have the extension ‘.tlk’. The user is free to customise or create ‘.tlk’ data files; the format of these files is detailed in 6.1.
The application may be run directly from floppy disk or copied to the hard disk of the host PC. No other installation is required.
The application comprises:
These files should be installed to the same location on the target machine, in the same directory (folder). Both are required for operation of the application.
This section describes use of the RESTalk application.
The first byte (byte zero) is the least significant byte of a data set.
USB traffic flows in two directions:
Double-click the 'RESTalk.exe' application from Windows Explorer.
A shortcut icon to the application may be placed on the desktop or Start menu if desired.
The version is displayed on starting the application or by clicking the top-left mini-icon from the Main Dialog (5.5) and selecting ‘About RESTalk…’.
The ‘key press’ note is further explained in 5.12.5.
The large Log display shows all communications with the modules with some limited explanation.
The data received or transmitted is shown prefixed with a length in square brackets, e.g.
[4] 01 02 03 04
The width of the columns in the display may be changed by dragging the right separator bar in the column headings. Double-clicking this separator will resize the column to match its contents. To maintain speed, the log is limited to 32,000 entries, at which point the top-most (oldest) entries will be deleted.
The Log will keep the latest logged items in view by default, unless the log is scrolled backwards, when the same position relative to the end of the log will be maintained.
This section controls the opening and closing of modules, the selection of modules for monitoring (Enable/Disable), and the module currently selected as target for transmissions.
The display lists all the modules known of, in the order that they were opened,with their type, ID, and handle. The 'Close All' button will close all modules currently open by RESTalk; the 'Open All' button will close all currently open modules, query the number of available modules, and open all those it can. Note that the example display shown indicates a module ID clash ‑ there are two modules of the same type with the same ID, which makes them indistinguishable from each other.
The 'Enable' and 'Disable' buttons allow the selected module to be added to or removed from the list of those being monitored in the Log display.
When a module is enabled and connected the 'Ad-hoc' button beside the Send List may be used to send one-off data to the selected module (see 5.11).
The Display Options change the formatting of messages (both Command and Reply) when displayed and inhibit display of some replies. These options can be changed at any time. The Loopback Test will set these options to default values that may be subsequently overridden.
The Timestamps option cannot be disabled, and the Interpretation of messages is currently not implemented.
The Clear button will clear the Log display.
RESTalk starts with no modules open. RESTalk opens all available modules if 'Open All' is pressed, or opens specific modules if enabled in the Log and polling is started. The modules remain open until 'Close All' is pressed, the module is physically unplugged and 'Open All' is pressed, or RESTalk is exited.
The Start button begins monitoring (reading) of all enabled modules and allows modules to be written (see 5.10). Pressing a second time (Stop) halts the polling. If a connection to a specific module does not exist or is lost, then while this button is depressed a (re-)connection will be attempted every second.
The Loopback Test button is specific to the currently selected module, and described in 5.15. Pressing a second time terminates the test, disconnects from the module, and displays statistics.
The Multi-Message Test button is specific to the currently selected module, which should be connected. The test is described in 5.16. Pressing a second time terminates the test and displays statistics.
The Reset button attempts to reset the currently selected module.A reset affects the connection status of the module so the function is only available when the module is disconnected.
One or more commands are sent to the currently selected module from the list of commands shown in the bottom right ‘Send List’ section of the display, or to any module using data typed in manually using the 'Ad-hoc' button.
If you wish to send some data ad-hoc then the 'Ad-hoc' button will allow you to enter data directly for transmission.
Choose the module number to send to and type the data to be transmitted in the lower edit box. The data can be specified as hexadecimal digits (e.g. 0D 0A) or ASCII, in double-quotes. Comments can also be included, in brackets.
The contents of this dialog are preserved (albeit without formatting) until the program exits, except for the module number. Every press of the 'Ad-hoc' button will automatically change the module number specified to the currently selected module number in the main dialog.
Commands from this list may be sent in 3 ways:
The width of the columns in the list of messages may be changed by dragging the right separator bar in the column headings. Double-clicking this separator will resize the column to match its contents. The list of messages is limited to 1,024 entries.
The operation of the ‘Send Menu’ section of the display is detailed below.
To add to the list of commands available select ‘Add to send list…’ and choose one or more ‘.tlk’ files (see 6.1). Adding always occurs to the end of the list and the same file may be added more than once, producing rapid repeated transmission.
Note that an upper limit of 1,024 messages is applied to the list of messages.
For convenience the default filename offered is ‘init.tlk’.
A selection in the list of messages can be made using a combination of the mouse, single-clicking, Shift and Ctrl keys. ‘Send selected’ will send the selected messages in the order listed.
To send messages in a ‘.tlk’ file out-of-order either copy and edit the ‘.tlk’ file or ‘Add’ the file many times to the list.
This sends all commands listed in sequence. As each command is sent the list of messages is scrolled and the current transmission highlighted.
This clears the list of messages.
Beside each message listed is a shortcut key (blank = space). If the Log display has the keyboard focus then pressing the shortcut key will prompt transmission of all messages assigned this key, in order.
The keyboard shortcut only works if the Log display is receiving keyboard input. To ensure this, click anywhere on the Log before pressing the key. There is a note on the ‘About’ dialog as a reminder.
If the keypress
shortcuts don’t work, click on the Log display.
Strategic use of the key shortcuts in combination with the ‘Send selection’ and ‘Send All’ buttons usually avoids the need to create new ‘.tlk’ files provided the commands required are defined in a ‘.tlk’ data file already.
Press the ‘Connect’ button and messages received from all enabled modules will be logged according to the Display Options.
Press the ‘Connect’ button a second time to disconnect from all modules.
1) Select the module you want to send to by choosing its number as the Target Module.
2) Ensure the module you wish to send to is Enabled (click 'Enable' if possible).
3) Ensure you are ‘Connected’ to the module.
4) Either choose one or more messages to send from the Send Menu, or use the ad-hoc send feature and type the data in manually.
5) If using the Send Menu (see 5.12), ensure the message(s) to transmit are listed in the ‘Send’ section in the bottom right of the display. If more commands are required, use ‘Add’ to add the commands required. If the ‘.tlk’ file does not exist for the command required then make one using the file format in 6.2 and 'Add' it. Then either:
a. Select the command(s) to transmit and ‘Send selected’, or
b. ‘Send All’, or
c. Click on the Display Log and press the shortcut key for the set of messages required.
6) If you want to type in the data to transmit, click the 'Ad-hoc' buttons and type in the data to transmit (see 5.11).
This feature is
currently not relevant for RES I/O Modules.
This mode provides a simple ‘delayed loopback’ of messages. When a particular message is received from the selected module it is sent back with a different message ID. The turnaround can be delayed from 0 through 60 seconds. This is used for testing the integrity of the link.
The Trigger ID is the 29-bit message ID sought, specified in hexadecimal (range 00000000 to 1FFFFFFF). The delay is specified in milliseconds from 0 to 60,000. The Response ID is the ID used for the response.
This feature is
currently not relevant for RES I/O Modules.
This automates sending multi-part messages to the module, and confirming that they are acknowledged and processed correctly. The test is started and stopped manually and displays results when it is disabled.
A ‘.tlk’ command data file contains a list of module commands suitable for transmission to a module over USB. It may assign ‘shortcut keys’ to any, all, or none of the messages it contains so that the messages can be invoked using a key press. The file is loaded into the ‘Send Menu’ section of the Main Dialog using the ‘Add’ button.
A ‘.tlk’ file is a set of ASCII lines containing any combinations of the following three commands separated by spaces or commas:
Command |
Description |
(…) |
Comment. Note: Brackets cannot be nested. |
key X |
Assign key X to this line. If X is alphanumeric it is less likely to have special meaning; some symbolic keys are reserved. The key is not case-sensitive. |
message “(comment) <hex> <hex>…” |
Message data (with comment for display). Bytes are listed in transmission order (conventionally LSByte first). |
A good example is:
(enable Video output)
key V, message "(Video on) 01 00 00 00"
The comment on line 1 is ignored; keystroke ‘V’ is assigned the message on line 2, which itself has a comment which is displayed in the Send Menu section of the Main Dialog but otherwise ignored.
A poor example is:
(not)message"(Video Audio and Motors) 0E 02 0E (displayed) 00 0010" key ,
The command ‘key’ takes the next (non-space) character as the keystroke; this line therefore assigns the 6-byte message 0E 02 0E 00 00 10 to keystroke ‘,’ (which is symbolic and usually reserved), with a comment that is ‘displayed’, and a comment that is ‘not’.
A message without a key assignment is assigned to the ‘space’ key. A key without a message is ignored.
The ‘.tlk’ file may contain many messages using many different shortcut keys. The same message may be repeated, as can the shortcut key. This allows whole sequences to be composed at run-time by adding more and more files to the Menu using the same keypress.