Canon EF-232 User Manual

0 (0)

Canon EF-232 Library

User Manual

Manual Rev 1.3

10/16/09

This manual covers library versions up to 20c and bootloader versions up to 45.

Birger Engineering, Inc. 38 Chauncy St #1101 Boston, MA 02111 http://www.birger.com

Go to Table of Contents


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

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

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

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

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

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.1Bootloader 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.2Aperture 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 f- number 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.3Legacy 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

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.4Mapped 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.5Focus 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.6Legacy 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

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.7Blocking 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.8Terse 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

3.9Status 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.1Focus 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.2Aperture 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.3Focal 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

3.9.4Miscellaneous 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.5Lens 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

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

4 How to Read the Command References

Each command page is organized as follows:

Applicable Library

Versions

Command Name (command)

Command Type	: New/Legacy or both
Syntax	: What is entered as the complete command
Returns	: The information or exact string returned

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

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

v18+

5.1Bootloader 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>

Go to Table of Contents

v10+

5.2Define 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

v18+

5.3Dump 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

v18+

5.4Distance 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

v10+

5.5Define 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

v16+

5.6Servo 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

v16+

5.7Exit 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>

In bootloader!

ex <CR>

BEI Boot Executive, v44

Go to Table of Contents

+ 51 hidden pages