Canon EF-232 User Manual
Canon EF-232 Library
User Manual
© 1999-2009 Birger Engineering, Inc.
Manual Rev 1.3
10/16/09
This manual covers library versions up to 20c and bootloader versions up to 45.
Go to Table of Contents
Birger Engineering, Inc.
38 Chauncy St #1101
Boston, MA 02111
http://www.birger.com
2
1 Table of Contents
1 Table of Contents ....................................................................................... 3
2 Quick Reference Tables ............................................................................ 5
Table 1. Library Command Quick Reference .......................................................... 5
Table 2. Bootloader Command Quick Reference ..................................................... 7
3 General Notes on Using the Library ........................................................ 8
3.1 Bootloader vs. Library ............................................................................................ 8
3.2 Aperture Positioning ............................................................................................... 8
3.3 Legacy Focus Positioning ....................................................................................... 8
3.4 Mapped Absolute Focus Positioning ..................................................................... 9
3.5 Focus Drift ............................................................................................................... 9
3.6 Legacy vs. New Commands .................................................................................... 9
3.7 Blocking vs. Non-Blocking Commands ............................................................... 10
3.8 Terse vs. Verbose Reporting Modes .................................................................... 10
3.9 Status Strings ......................................................................................................... 11
3.9.1 Focus Position Status ....................................................................................... 11
3.9.2 Aperture Position Status ................................................................................... 11
3.9.3 Focal Length and Aperture Range Status ........................................................ 11
3.9.4 Miscellaneous Status Flags .............................................................................. 12
Table 3. Status Flags ............................................................................................. 12
3.9.5 Lens Connection Messages .............................................................................. 12
3.10 Errors in Command Processing ......................................................................... 12
Table 4. Error Codes ............................................................................................. 13
4 How to Read the Command References ................................................ 14
5 Library Command Reference ................................................................ 15
5.1 Bootloader Version (bv) ........................................................................................ 16
5.2 Define Aperture (da) ............................................................................................. 17
5.3 Dump EEPROM (de) ............................................................................................ 18
5.4 Distance Stops (ds) ................................................................................................ 19
5.5 Define Zoom (dz) ................................................................................................... 20
5.6 Servo Focus with Checksum (eh) ......................................................................... 21
5.7 Exit to Bootloader (ex) .......................................................................................... 22
5.8 Focus Absolute (fa) ............................................................................................... 23
5.9 Focus Distance (fd) ................................................................................................ 24
5.10 Fast Focus (ff) ...................................................................................................... 25
5.11 Focus Positions (fp) ............................................................................................. 26
5.12 Get Statuses (gs) .................................................................................................. 27
5.13 Hardware Version (hv) ....................................................................................... 28
5.14 Lens Identification (id) ....................................................................................... 29
5.15 Initialize Aperture (in) ........................................................................................ 30
5.16 Image Stabilization (is) ....................................................................................... 31
5.17 Learn Absolute Focus Range (la) ...................................................................... 32
5.18 Cached Extended Lens Status (lc) ..................................................................... 33
5.19 Library Loaded (ll) ............................................................................................. 34
Go to Table of Contents
3
5.20 Lens Presence (lp) ............................................................................................... 35
5.21 Immediate Extended Lens Status (ls) ................................................................ 36
5.22 Library Version (lv) ............................................................................................ 37
5.23 Move Aperture Absolute (ma) ........................................................................... 38
5.24 Move Aperture to Closed Position (mc) ............................................................ 39
5.25 Move Focus Incremental (mf) ............................................................................ 40
5.26 Move Focus to Infinity (mi) ................................................................................ 41
5.27 Move Aperture Incremental (mn) ..................................................................... 42
5.28 Move Aperture to Opened Position (mo) .......................................................... 43
5.29 Move Focus to Zero (mz) .................................................................................... 44
5.30 Print Aperture Position (pa) .............................................................................. 45
5.31 Print Focus Position (pf) ..................................................................................... 46
5.32 Lens Power (pl) ................................................................................................... 47
5.33 Set Response Modes (rm) ................................................................................... 48
5.34 Set EEPROM Byte (se) ....................................................................................... 49
5.35 Set Focus Counter Offset (sf) ............................................................................. 50
5.36 Set GPIO (sg) ....................................................................................................... 51
5.37 Set Special Modes (sm) ....................................................................................... 52
5.38 Print Serial Number (sn) .................................................................................... 53
5.39 Set Spontaneous Responses (sr) ......................................................................... 54
5.40 Short Version String (vs) .................................................................................... 55
5.41 Write EEPROM Parameters (we) ..................................................................... 56
6 Bootloader Command Reference ........................................................... 57
6.1 Banner Echo (be) ................................................................................................... 58
6.2 Boot Library (bl) ................................................................................................... 59
6.3 Baud Rate (br) ....................................................................................................... 60
6.4 Baud Store (bs) ...................................................................................................... 61
6.5 Hardware Version (hv) ......................................................................................... 62
6.6 Library Version (lv) .............................................................................................. 63
6.7 Query Communications Port (qp) ....................................................................... 64
6.8 Set Response Modes (rm) ..................................................................................... 65
6.9 Escape from Port Routing (routeesc,) ................................................................. 66
6.10 Setup Port Routing (rt) ....................................................................................... 67
6.11 Serial Number (sn) .............................................................................................. 68
6.12 Suppress Prompt (sp) .......................................................................................... 69
6.13 Long Version String (vn) .................................................................................... 70
6.14 Short Version String (vs) .................................................................................... 71
6.15 Write Configurations to EEPROM (wc) ........................................................... 72
6.16 XModem Firmware Download (xm) ................................................................. 73
Go to Table of Contents
4
2 Quick Reference Tables
Table 1. Library Command Quick Reference
Command Arguments Description
bv Print the bootloader version.
da Print aperture information.
de Dump EEPROM.
ds Print distance stops.
dz Print the zoom range.
eh pos,checksum Set absolute lens focus position (0…0x3FFF).
ex Exit to the bootloader.
fa position Move focus to absolute position.
fd Print focus distance range.
ff position Fast focus.
fp Print the raw focus positions.
gs Echo current device and lens statuses.
hv Print the hardware version.
id Print basic lens identification (zoom and f-number).
in Initialize the aperture motor. Aperture will fully open.
is {0, 1} Turn image stabilization off/on.
la options Learn the focus range.
lc Print cached lens status
ll Library loaded check.
lp Lens presence.
ls Query lens for status immediately and print.
lv Print the library version string.
ma stop Move aperture to absolute position.
mc Move aperture to the fully stopped down limit.
mf Move focus incremental.
mi Move focus to the infinity stop.
mn num_stops Move aperture incremental.
mo Move aperture to completely open.
mz Move focus to the zero stop.
pa Print the aperture position.
pf Print the focus position.
pl {0, 1} Lens power
rm verbose[,new] Set response modes.
se byte,val Temporarily set non-volatile (EEPROM) byte.
sf count Set the focus counter.
sg port,state Set GPIO.
sm mode_flags Set special modes.
sn Print the device serial number.
Go to Table of Contents
5
sr {0, 1} Set spontaneous responses off/on.
vs Print the short version string.
we serial_number Write non-volatile parameters to EEPROM.
Go to Table of Contents
6
Table 2. Bootloader Command Quick Reference
Command Arguments Description
be Print the banner string.
bl Boot library.
br baud_rate[,prt] Set baud rate, argument is actual baud rate / 100.
bs Obsolete – commit baud rate setting.
hv Print the hardware version.
lv Print version of loaded library.
qp Query current port number.
rm verbose[,new[,prt]] Set response modes.
routeesc, depth Escape from port routing.
rt port,depth Route through to port with assigned depth.
sn Print the unit serial number.
sp {0, 1} Suppress prompt.
vn Print the long version string.
vs Print the short version string.
wc Write all configurations to EEPROM.
xm unlock_sn XModem firmware download.
Go to Table of Contents
7
3 General Notes on Using the Library
This section describes the differences between legacy library commands (libraries
up to version 15) and new library commands (versions 16 and upward), the differences in
command behavior, and the differences between the bootloader and library. It is also the
reference for the basic behaviors of the library.
3.1 Bootloader vs. Library
Prior to version 16 of the library, the bootloader and library code were integrated
together. While the library was still separately upgradeable, the bootloader and library
worked together. All commands were available for access all of the time. All commands
blocked until they were finished.
Version 4 of the hardware shipped with a new bootloader and new command
model. Bootloader commands are only available from within the bootloader, and library
commands are only available from within the library, except where the functionality is
duplicated. If a command with the same name exists in the bootloader and library then it
will perform the same function in both instances.
The bootloader transfers execution to the library for normal operation, and the
library handles normal command processing. Commands can be blocking or nonblocking (they return immediately while lens processing occurs “in the background”).
Firmware upgrading can only be done through the bootloader.
3.2 Aperture Positioning
Aperture positioning is generally measured in ¼ stop increments. However, the
input to the aperture positioning commands is an integer and the reported aperture
positions are f-number times ten or a corresponding integer number of ¼ stops. For
example, if f28 is reported for an aperture position, then it is indicating that the actual fnumber is 2.8. If this is the wide-open position then it is considered the zero position, and
the input to the absolute aperture position commands would be zero. If aperture
measurement is not reported as ¼ stops then the exception will be noted where
applicable.
A value of one would indicate ¼ stop from the full-open position (2.8) towards
the closed position, which would be approximately 3.1. If the aperture position is then
reported in this state, the number one would be reported as the position in number of ¼
stops from the wide-open (zero) position, and the f-number would be reported as f30.
Note that the library uses integer rather than floating point math, so the f-number reported
is close to, but not exactly the mathematical f-number.
3.3 Legacy Focus Positioning
Focus positioning for legacy commands is performed with respect to the encoder
positions directly reported by the connected lens. Each lens will have a different encoder
count for its focusable range, and the encoder count for the zero position will almost
Go to Table of Contents
8
never be zero, in fact it will usually be random, changing with each power cycle of the
lens. However, the focus counter command 'sf' can be used to make any number the
reference for the zero position. The lens can be focused anywhere from zero to infinity by
using commands to learn the full encoder count range and then applying those values to
the positioning commands. For example, a move to zero and then a set focus counter to
zero will establish the value of zero as the position for the minimum focus distance of the
lens. A move to infinity will then report the full number of encoder counts that it took to
get there.
3.4 Mapped Absolute Focus Positioning
Library versions 16 and up introduce the ability to perform absolute positioning
on a fixed scale. This fixed scale is a 14-bit range from 0 to 16383 (hex 3FFF). The range
of the lens from the zero stop to the infinity stop is mapped into this numerical scale. The
14-bit range is generally much larger than the encoder range returned by the lens, and
therefore a small change in the mapped position often will not result in a change to the
focus position.
The mapped focusing feature is highly recommended when using a control
surface to alter focusing. It allows use of a scale that is always fixed between the zero and
infinity positions. However, if the control surface is not capable of sending small enough
changes in the mapped position, then jumpy focusing behavior can occur. Ideally the
control surface should also have a 14-bit range, but a smaller range is okay as long as it is
several times larger than the lens' encoder range. The control surface should have at least
12-bit resolution to meet this requirement for all lenses tested to date. A smaller
resolution will still work, but focusing will not be as smooth or precise.
3.5 Focus Drift
Most lenses will experience drift of the focus mechanism. This results in a change
of the encoder position associated with a particular stop. Generally the lens will lose or
gain a few encoder counts when hitting a stop. The lens may also lose positioning just
during normal focusing, and it can be made worse if the focus move is small. The betterconstructed, more-expensive lenses will drift far less than the cheaper lenses. Drift must
be accounted for by relearning the encoder positions of the zero and infinity stops.
3.6 Legacy vs. New Commands
The library as shipped emulates the legacy command protocol. In this protocol all
commands are case insensitive and are acknowledged with the string 'OK' to indicate that
the command was received. This is followed by any output that the command may have,
after any delay that the command may need to complete its processing. Commands that
are marked as 'new' in this manual will still conform to this behavior.
It is possible to change this behavior so that the 'OK' string is not emitted. In this
case commands will report only their output, or a confirmation if they have no regular
output. These modes can be configured with the response mode command, and are
Go to Table of Contents
9
described further under that command heading. When the new library protocol is active,
commands become case-sensitive. They must be entered as lower-case only.
There are general enhancements that apply regardless of mode or command.
White space is now permitted and commands can have multiple arguments, each
separated by a comma.
3.7 Blocking vs. Non-Blocking Commands
In the legacy libraries (versions 15 and lower), all commands were blocking. In
other words, they needed to finish before any other command could be sent. The new
libraries introduce two new servo routines: an aperture servo and a focus servo. There are
new commands to use these routines. These new commands return immediately and the
library handles the necessary lens processing in the background.
If you intend to have multiple devices talking to the lens controller over several
serial ports, then all lens commands and status queries must use the new commands that
operate in the background. Otherwise, a device on one port will hold off the other devices
from getting their communications through in a timely manner. Also, the library
automatically coordinates the lens processing so no conflicts occur, which would not be
possible if using the legacy commands from multiple serial ports.
3.8 Terse vs. Verbose Reporting Modes
The device can be configured to report in two different modes in addition to
legacy/new protocols using the response modes ('rm') command. In terse mode,
characters are not echoed back from the device, and all commands return a single
number, zero for no error or a non-zero error value. Note that even commands that would
normally return a status string will not do so in terse mode as long as they are marked as
legacy commands. New commands will always echo their output if they have status to
print.
In verbose mode, all characters input to the device are echoed back out, and
commands will print their full status strings as usual. If set to both verbose and new
protocol modes, then a question mark will be emitted by the device for unknown
commands. Verbose mode is most useful when manually controlling the device through a
terminal program.
Go to Table of Contents
10
3.9 Status Strings
Starting with library version 18, there are a standard set of status strings that can
be queried for or spontaneously emitted from the device. The spontaneous emissions are
off by default but can be turned on with the command 'sr'.
3.9.1 Focus Position Status
Format: %:xxxx
Where xxxx is a 4-digit hexadecimal number indicating the current focus position
of the lens in the mapped range (0...3FFF).
3.9.2 Aperture Position Status
Format: &:xx
Where xx is a 2-digit hexadecimal number indicating the current aperture position
in 1/8 stops. Note that if the aperture position is unknown, for example if a lens has been
connected but not initialized, then the status string will be:
&:?
3.9.3 Focal Length and Aperture Range Status
Format: @:<focal_length>mm,f<min_f>,<num_stops>,f<max_f>
Where <focal_length> is a decimal number for the current focal length in
millimeters, <min_f> is a decimal number for the current minimum f-number times ten,
<num_stops> is a decimal number for the number of ¼ stops available, and <max_f> is a
decimal number for the current maximum f-number times ten.
Go to Table of Contents
11
3.9.4 Miscellaneous Status Flags
Format: #:xxxx
Where xxxx is a 4-digit hexadecimal number indicating the current value of the
flags. The flags are given in the following table.
Table 3. Status Flags
Bit(s) Description
0 Port RA0 is input; 0 = output, 1 = input.
1 Port RA1 is input; 0 = output, 1 = input.
2 Port RA0 value; 0 = low, 1 = high.
3 Port RA1 value; 0 = low, 1 = high.
4 Aperture initialized; 0 = not initialized, 1 = initialized.
5 Manual focus; 0 = lens is in autofocus, 1 = lens in in manual focus.
6 Focus mode; 0 = normal; 1 = sticky lenses
7-15 Reserved.
3.9.5 Lens Connection Messages
When in new-protocol mode, a spontaneous string will be emitted when a lens is
connected or disconnected from the unit. These strings are:
Lens Connected.
and
Lens Disconnected.
3.10 Errors in Command Processing
If a command fails it will report a numerical error code. In terse mode the number
is returned by itself, while in verbose mode and new-protocol mode the return string will
be:
ERRx
Where x is the numerical error code. The possible error codes that can be returned are
given in the following table.
Go to Table of Contents
12
Table 4. Error Codes
Error Code Description
0 No error.
1 Unrecognized command.
2 Lens is in manual focus mode.
3 No lens connected.
4 Lens distance stop error.
5 Aperture not initialized.
6 Invalid baud rate specified.
7 Reserved.
8 Reserved.
9 A bad parameter was supplied to the command.
10 XModem timeout.
11 XModem error.
12 XModem unlock code incorrect.
13 Not used.
14 Invalid port.
15 License unlock failure.
16 Invalid license file.
17 Invalid library file.
18 Reserved.
19 Reserved.
20 Not used.
21 Library not ready for lens communications.
22 Library not ready for commands.
23 Command not licensed.
24 Invalid focus range in memory. Try relearning the range.
25 Distance stops are not supported by the lens.
Go to Table of Contents
13
4 How to Read the Command References
Each command page is organized as follows:
Command Name (command)
Command Type : New/Legacy or both
Syntax : What is entered as the complete command
Returns : The information or exact string returned
Applicable Library
Versions
Description
A description of how the command is used.
Examples:
One or more examples of how the command is used. The command syntax is
shown as normal text, information returned from the device is shown in italic text. The
command confirmation for legacy behavior ('OK') is not shown.
Go to Table of Contents
14
5 Library Command Reference
The following pages contain descriptions of the commands that are available from
within the library. These commands will not be active while in the bootloader, however
the bootloader may have commands with the same name also implemented, in which case
they will perform the same function.
Go to Table of Contents
15
v18+
5.1 Bootloader Version (bv)
Command Type : New
Syntax : bv
Returns : Bootloader version number
Description
This command will print the version of the bootloader code from within the
library. Therefore exiting to the bootloader is not needed to read the revision information.
Example:
bv <CR>
44
Go to Table of Contents
16
v10+
5.2 Define Aperture (da)
Command Type : Legacy
Syntax : da
Returns : f<min>,<num_stops>,f<max>
Description
This command will print the the aperture range of the connected lens. The range
is printed in three parts as follows:
fmin,num_stops,fmax
The item printed is the letter 'f' followed by the current minimum f-number. This is
followed by a comma and the total number of stops in ¼ stops that can be commanded to
the lens. This is then followed by another comma, the letter 'f', and the current maximum
f-number.
Example:
da <CR>
f28,28,f320
Go to Table of Contents
17
v18+
5.3 Dump EEPROM (de)
Command Type : New
Syntax : de
Returns : EEPROM parameters as hexadecimal bytes
Description
This command will dump a hexadecimal stream of bytes that corresponds to the
non-volatile parameters stored in EEPROM. The commonly configured parameters are
almost always available through other commands, so this command is used to gain access
to the remaining parameters. These parameters are often low-level timing configurations.
Contact Birger Engineering if you think your programming needs might require
modification to these parameters.
Go to Table of Contents
18
v18+
5.4 Distance Stops (ds)
Command Type : New
Syntax : ds
Returns : $:<far>:<near>:<encoder>
Description
This command will execute a move to the zero stop of the lens. It will then
advance the lens through its focus range and print the distance stops as reported by the
lens. The distance stops take the form:
$:<far>:<near>:<encoder>
Where <far> is a 4-digit hexadecimal number representing the far distance of the stop in
centimeters, <near> is another 4-digit hexadecimal number representing the near distance
of the stop in centimeters, and <encoder> is a 4-digit hexadecimal number of the raw
encoder count of the lens. The command finishes with a move to the focus motor infinity
stop to read its position followed by a return to the original focus position. Issuing this
command while it is already in progress will cancel further distance reporting. Other lens
control commands will not work or should not be issued while this command is in
progress.
The infinity position is reported as ffff hexadecimal. The infinity position reported
as a distance stop may not actually correspond with the infinity focus position resulting
from the focus motor's infinity stop. These are often two different stops in the lens
construction. Not all lenses are capable of reporting distance stops.
Example:
ds <CR>
$:0021:0020:fe01
$:0023:0021:feb4
$:0025:0023:ff23
$:0026:0025:ffb1
$:0029:0026:0066
$:0035:0029:0216
$:005f:0035:0436
$:008b:005f:04f6
$:017a:008b:05e8
$:045d:017a:062f
$:ffff:045d:0655
$:ffff:ffff:06bf
$:DONE
Go to Table of Contents
19
v10+
5.5 Define Zoom (dz)
Command Type : Legacy
Syntax : dz
Returns : <min_focal_length>mm,<max_focal_length>mm
Description
This command will print the zoom range of the lens. The first number printed is
the minimum focal length in millimeters followed by 'mm'. This is followed by a comma,
the maximum focal length of the lens, and the letters 'mm'. Prime lenses will print the
same value for minimum and maximum focal length.
Example:
dz <CR>
18mm,55mm
dz <CR>
50mm,50mm
Go to Table of Contents
20
v16+
5.6 Servo Focus with Checksum (eh)
Command Type : New
Syntax : eh <absolute_position>,<checksum>
Returns : Nothing
Description
This command is used to set the focus position of the lens on an absolute 14-bit
scale from 0 to 3FFF hexadecimal. The command requires a checksum that is the bit-wise
exclusive-OR of the four 4-bit digits of the position. This command executes through the
servo focus routine and returns immediately.
All four digits of the position must be specified, including leading zeros. If the
correct number of digits is not sent or the checksum is incorrect, then the command will
be ignored.
Examples:
eh0000,0 <CR>
eh1000,1 <CR>
eh3fff,c <CR>
Go to Table of Contents
21
v16+
5.7 Exit to Bootloader (ex)
Command Type : New
Syntax : ex
Returns : In bootloader!
Description
This command exits library processing and hands control to the bootloader.
Firmware (library) upgrades must be performed through the bootloader. There are several
other commands that can only be accessed through the bootloader.
The return response from this command depends on which protocol mode is
active, legacy vs. new, and terse vs. verbose, but the string 'In bootloader!' will always be
returned.
Examples:
ex <CR>
r!
In bootloader!
ex <CR>
BEI Boot Executive, v44
(c)2008 Birger Engineering, Inc.
In bootloader!
Go to Table of Contents
22
Loading...