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

 

1.          Introduction

This document describes use of the RESTalk PC application.

1.1          Product Overview

RESTalk is a test harness for demonstrating and proving I/O using the Red Earth Systems range of USB I/O modules.

1.2          References

Ref

Title

Author

Description

API

RESIO API Specification

Red Earth Systems Limited

A description of the RESIO API to the RES I/O Modules.

 

1.3          Readership

This document is targeted at any person involved in using the RES I/O Modules.

1.4          Acknowledgements

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.

1.5          Glossary

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.

 

2.          Introduction

2.1          General

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.

2.2          Purpose

This document is the User Guide for the RESTalk application.

2.3          Scope

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.

 

3.          System Overview


 


This diagram is for Windows 2000 and Windows XP only. A Windows 98SE/Me system has a different configuration.

 

4.          Installation

4.1          System Requirements

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.

4.2          Components

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.

4.3          Installation

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:

 

  1. The RESTalk.exe application.
  2. The RESIO.dll API.

 

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.

 

5.          User Guide

This section describes use of the RESTalk application.

5.1          Byte Ordering Convention

The first byte (byte zero) is the least significant byte of a data set.

5.2          Commands and Replies

USB traffic flows in two directions:

 

5.3          Running RESTalk

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.

5.4          Version / About RESTalk

 

 

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.

5.5          The Main Dialog

5.6          Log

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.

5.7          Module List

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).

5.8          Display Options

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.

5.9          Mode (latched buttons)

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.

5.10          Send List

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.

5.11          Sending Ad-hoc Data

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.

5.12          Sending Data from the Send List

Commands from this list may be sent in 3 ways:

 

  1. Send Selected: Send one or more commands from the list that have been selected.
  2. Send All: Send all commands in the list.
  3. Key shortcuts: Send all messages in the list assigned a given ‘key’.

 

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.

5.12.1          Add

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’.

5.12.2          Send Selected

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.

5.12.3          Send All

This sends all commands listed in sequence. As each command is sent the list of messages is scrolled and the current transmission highlighted.

5.12.4          Clear

This clears the list of messages.

5.12.5          Key shortcuts

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.

5.13          Watching for Module Replies

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.

5.14          Sending one or more Module Commands

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).

5.15          Loopback Test

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.

5.16          Multi-Message Test

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.

 

6.          Data File Formats

6.1          ‘tlk’ Command Files

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.

6.2          ‘.tlk’ File Format

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.