top bar

UserDefinedSerial

Revision as of 15:08, 18 August 2014 by Mark Tsuchida (Talk | contribs)

UserDefinedSerial

Summary:Control arbitrary serial-based shutters and state devices
Author:Mark Tsuchida
License:BSD
Platforms:All platforms (uses serial port)
Serial port settings:Depends on device
Since version:1.4.19 (nightly 20140813)

The UserDefinedSerial device adapter will allow you to control any shutter or state device (turret, changer, switch, etc.) that uses the serial port for communication and operates using a simple serial protocol.

You will need to know the correct serial port settings for the device, as well as the command protocol for controlling the device.

Configuration (Step 1: write-only communication)

There are quite a few properties that need to be set correctly, so it is simplest to first configure the device to move in response to commands. The device adapter will remember the last-set state (shutter open/close or state device position) in software, so things will stay in sync if the device is reliable (doesn't encounter errors) and you don't manually operate it. For devices that do not have commands to query state, this will be the only configuration step.

Common settings

Start by setting these properties in the Hardware Configuration Wizard:

  • Port - Set this to the correct serial port (COM port on Windows). Also, set the port settings to the correct values for the device.
  • Command mode - The format of the commands to be sent. More on this below.
  • Response detection - Leave at "Ignore responses"
  • Initialize-command (optional) - If there is a command that needs to be executed to set up the device for use, enter it here. Otherwise, leave it blank.
  • Shutdown-command (optional) - If there is a command that should be executed when finished using the device, enter it here. Typically, leave it blank.

Command mode

Usually, serial commands are short strings (made up of letters, numbers, and punctuation). The device manual should indicate how these commands are terminated: CR, LF, or CRLF. Select the corresponding ASCII mode.

ASCII-no-terminator can be used in unusual cases where the terminator is not one of the three provided options, or where a subset of commands need to be sent without a terminator. In such cases, the terminator must be included in every command string.

Some devices use binary commands, made up of raw byte values and no terminator. In such cases, select Binary.

How to enter commands

Special control characters and commas in commands need to be entered according to special rules. See the later section on "How to enter command and response strings".

UserDefinedShutter

  • Open-command - Enter the command that opens the shutter.
  • Close-command - Enter the command that closes the shutter.

The remaining properties can be left blank for now.

UserDefinedStateDevice

  • Number of positions - Set this to the number of positions. (E.g. 8 if you have an 8-position filter wheel.)

In addition, the commands for setting each position need to be set. To do so, first finish and save the hardware configuration; then open the Device Property Browser. Enter set the following properties:

  • SetState-command-n (where n is a number) - Enter the command that tells the device to move to position n.

The remaining properties of UserDefinedStateDevice can be left blank for now.

Now, to cause the SetState commands to be remembered in your hardware configuration file, add (or append to) the System-Startup configuration preset (see Micro-Manager Configuration Guide). In this case, you will want to include all the SetState-command-n properties in the System configuration group's Startup preset.

Configuration (Step 2: checking device responses)

Most devices respond to commands with a specific acknowledgement. (Some devices don't send anything back to the computer; if that is the case with your device, you are done configuring.)

It is useful to check the device's response in case it indicates an error. UserDefinedSerial currently supports checking command responses against a fixed string; an error is reported if the device fails to respond or responds with a string that differs from the expected one.

Choosing a response detection method

Devices that use an ASCII protocol typically terminate their responses with CR, LF, or CRLF, just like the commands (although the terminator is not necessarily the same one used for commands - check your device's manual). Some devices return 1 or a few bytes in a fixed-length format, without a terminator. In the Hardware Configuration Wizard, set the Response detection property accordingly:

  • Ignore responses - No responses are ever checked.
  • Terminator-CR - Responses are expected to be terminated with a CR (carriage return).
  • Terminator-CRLF - Responses are expected to be terminated with a CR followed by an LF (linefeed).
  • Terminator-LF - Responses are expected to be terminated with an LF.
  • Variable-length binary - Responses are binary bytes without a terminator. The expected number of bytes are read from the device.

Common settings

  • Initialize-response - Enter the expected response from the device after the initialization command is sent.
  • Shutdown-response- Enter the expected response from the device after the shutdown command is sent.

You do not have to specify a response string for every command. Where a response string is left empty, the response is simply ignored (not checked for).

UserDefinedShutter

  • Open-response - The expected response to the open command.
  • Close-response - The expected response to the close command.

UserDefinedStateDevice

In the Device Property Browser:

  • SetState-response-n (where n is a number) - The expected response to the SetState-command-n command.

(You will want to add these too to the System-Startup configuration preset.)

Configuration (Step 3: setting up device state querying)

(to be written)

UserDefinedShutter

(to be written)

UserDefinedStateDevice

(to be written)

Setting Delay

UserDefinedSerial devices do not (yet) support querying the device to detect the completion of motion. Instead, you can set fixed delays on the Delay page of the Hardware Configuration Wizard.

The Delay value should be the maximum time it takes the device to complete motion, measuring from the moment when the command is sent (or, if so configured, when the response is received).

How to enter command and response strings

(to be written) - C-language-style string escapes, except that hex escapes (\x??) are limited to two digits.

(TODO mention comma handling)

How commands are sent

(to be written)

How responses are checked

(to be written)

© Micro-Manager : Vale Lab, UCSF 2006-2011 | All Rights Reserved | Contact