Canon EF-232 Library User Manual 1.3
Contents
1. Go to Table of Contents 4 2 Quick Reference Tables Table 1 Library Command Quick Reference by Print the bootloader version SS da Print aperture information de Dump EEPROM ds Print distance stops az Print the zoom range eh pos checksum Set absolute lens focus position 0 0x3FFF Tex Sito the bootloader fd Print focus distance range SSS p Print the raw focus positions gs eho current device and lens statuses h Print the hardware version ia Print basie Tens identification oom and Enumber in initialize the aperture motor Aperture willfully open is f o Tumm image stabilization offfon m options Leam the focus range SSS Te Print cached fens status aT ribrary loaded check SS ip ens presence OOS Ts Query Tens for status immediately and print o Print the library version string ma sop Move aperture to absolute positon me Move aperture to the fully stopped down imit mf Move focus incremental mi Move focus to the infinity stop mn um stops Move aperture incremental Move aperture to completely open Move focus to the zero stop Print the aperture position SSS Print the focus position SSCS sn Print the device serial number SSS pf Set response modes sf Go to Table of Contents 5 __ 0 1 Set spontaneous responses off on Print the short version string ae gt ee Write non volatile parameters to EEPROM Go to Table of Contents 62. command is issued lt current_pos gt is the current focus position of the lens Example fp lt CR gt fmin 1303 fmax 1228 current 696 Go to Table of Contents 26 v18 5 12 Get Statuses gs Command Type New Syntax gs Returns Status strings Description This command prints complete status information in the form of the new status strings The status strings are described in Section 3 9 of this manual Example gs lt CR gt 1948 0a 100mm f28 28 320 0010 AOR oo Go to Table of Contents 27 v18 5 13 Hardware Version hv Command Type Legacy New Syntax hv Returns Device hardware version Description This command will print the hardware version of the device It exists up to library version 15 in the unified bootloader library The command does not appear in versions 16 and 17 of the library so obtaining the hardware version requires exiting to the bootloader for those versions Example hv lt CR gt 4 Go to Table of Contents 28 v10 5 14 Lens Identification id Command Type Legacy Syntax id Returns lt current_focal_length gt mm f lt current_min_f_number gt Description This command prints the basic lens identity For a zoom lens it will print the current focal length otherwise it prints the fixed focal length of the lens This is followed by a comma and the letter f followed by the current minimum f number that the lens is capable of multiplied by
3. 01234 Go to Table of Contents 53 v18 5 39 Set Spontaneous Responses sr Command Type New Syntax sr 0 1 Returns OK Description This command turns spontaneous responses on or off for the port over which the command is sent 0 for off 1 for on For status updates focus and aperture changes will be automatically broadcast to every other port in response to a change on any particular port If background lens querying is also turned on see command sm then changes in lens status focal length etc are broadcast to all ports Finally GPIO changes will also be broadcast to all ports Note that this does not cause commands to be echoed out rather updates take the form of status strings as given in Section 3 9 Spontaneous updates are set on a port by port basis The status changes are broadcast but only the communications ports over which this command has been sent to turn on responses will actually receive them Examples sro lt CR gt OK srl lt CR gt OK Go to Table of Contents 54 v16 5 40 Short Version String vs Command Type New Syntax VS Returns lt module gt v lt version gt Description This command prints the short version string that describes the code currently executing This string is given with the identifier s followed by the short module ID in lt module gt followed by the letter v followed by the decimal revision number The Canon EF 232 Library will return C2
4. Table 2 Bootloader Command Quick Reference be Prrinttthe banner string bE Boot library S O Obsolete commit baud rate setting Frnt the hardware version Print version of loaded library Query current port number m Print the unit serialnumber sp 0 1 Suppress prompt S vm i Print the long version string vs Print the short version string _ we Write all configurations to EEPROM 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 bootload
5. This command is used to set the state of the GPIO signals from the device Port 0 Signal RAO 1 Signal RAI State 0 Output low 1 Output high Input Examples sg0 0 lt CR gt DONE sgl 2 lt CR gt DONE Go to Table of Contents 51 v18 5 37 Set Special Modes sm Command Type New Syntax sm lt mode_flags gt Returns DONE Description This command is used to control special modes of the device lt mode_flags gt is given as a decimal number If you need to know more about how the modes work contact Birger Engineering Inc Bit Mode 0 Reserved 1 Reserved 2 1 Switch ma command to use the servo aperture routine 3 1 Turn on background lens querying 4 1 Show distance stop progress 5 1 Set focus mode for sticky lenses 6 Reserved 7 Reserved Examples sm4 lt CR gt DONE sml12 lt CR gt DONE Go to Table of Contents 52 v18 5 38 Print Serial Number sn Command Type Legacy New Syntax sn Returns Device serial number Description This command prints the device serial number The serial number is used as an input to various commands as an unlock code This command does not appear in versions 16 and 17 of the library so obtaining the serial number requires exiting to the bootloader for those versions Beginning with library version 19r the serial number is printed with leading zeros in a five digit field Example sn lt CR gt
6. 6 Focus mode 0 normal 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 l
7. EEPROM we Command Type New Syntax WC Returns OK Description This command will commit the temporary non volatile settings to EEPROM This will make the settings persist through power cycles The parameters that will be committed are the baud rates response modes and command prompt settings for all ports not just the port over which this command was sent Example wc lt CR gt OK Go to Table of Contents 72 Bootloader 6 16 XModem Firmware Download xm Command Type New Syntax xm lt serial_number gt Returns Enters XModem download Description This command is used to update the library firmware As a safeguard against inadvertently entering XModem download mode the device s serial number must be supplied as the command argument The serial number is parsed numerically so leading zeros are not significant The serial number is obtained with the sn command Any terminal program that supports XModem with 128 byte blocks and simple checksumming not CRC 16 can be used to download new library firmware Library firmware is obtained solely from Birger Engineering Inc Example xml1234 lt CR gt Go to Table of Contents 73
8. 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 better constructed 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 a
9. as the module ID Example vs lt CR gt S C2v17 Go to Table of Contents 55 v18 5 41 Write EEPROM Parameters we Command Type New Syntax we lt serial_number gt Returns DONE Description This command will commit the temporary non volatile settings to EEPROM This will make the settings permanent You may damage your device which will require sending it back to Birger Engineering if you commit bad parameters to the non volatile memory This command requires the device serial number as a confirmation The serial number is parsed numerically so leading zeros are not significant Example wel234 lt CR gt DONE Go to Table of Contents 56 6 Bootloader Command Reference This section describes commands available while the bootloader is active These commands are not available while the library is executing although the library may have some of the same commands also implemented Go to Table of Contents 57 6 1 Banner Echo be Command Type Legacy Syntax be Returns Birger Engineering Inc Description This command prints the device banner string Example be lt CR gt Birger Engineering Inc Go to Table of Contents Bootloader 58 Bootloader 6 2 Boot Library bl Command Type New Syntax bl Returns Depends on response mode settings Description This command boots the library code Control is transferred to the library and the library handles all further command
10. lens status by immediately querying the lens The status string is of the form outlined in Section 3 9 This command should be used if background querying is turned off see command sm Example ls lt CR gt 38mm f47 21 293 Go to Table of Contents 36 5 22 Library Version lv Command Type Legacy Syntax Iv Returns Full library identity string Description This command prints the full library identification string Example lv lt CR gt Canon EF 232 Library v17 Go to Table of Contents v10 37 v10 5 23 Move Aperture Absolute ma Command Type Legacy Syntax ma lt pos gt Returns DONE lt rpos gt f lt f_number gt Description This command moves the aperture mechanism to the specified encoder position specified in 14 stops from the fully open position indicated by the user in lt pos gt If an input value would move the aperture out of the legal range the value is set to the boundary i e min max aperture lt rpos gt is the actual position the aperture moved to in 4 stops from the fully open position and lt f_number gt is the absolute position given as the lens f number times ten Examples ma0 lt CR gt DONEO 35 ma5 lt CR gt DONES 54 Go to Table of Contents 38 v10 5 24 Move Aperture to Closed Position mc Command Type Legacy Syntax mec Returns DONE lt signed_num_steps gt f lt f_number gt Description This command will move the aperture
11. near gt lt encoder gt Where lt far gt is a 4 digit hexadecimal number representing the far distance of the stop in centimeters lt near gt is another 4 digit hexadecimal number representing the near distance of the stop in centimeters and lt encoder gt 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 lt CR gt 0021 0020 fe01 0023 0021 feb4 0025r 002 EEZ 0026 0025 ffb1 0029 0026 0066 0035 0029 0216 005 0035 0436 008b 005f 04f6 017a 008b 05e8 045da 017a 062f ffff 045d 0655 ffff ffff 06bf DONE MHA MN HNHN HH NUNN Go to Table of Contents 19 v10 5 5 Define Zoom dz Command Type Legacy Syntax dz Returns lt min_focal_length gt mm lt max_focal_length gt mm Description This command will print the zo
12. processing Example bl lt CR gt BEI Boot Executive v44 c 2008 Birger Engineering Inc Canon EF 232 Library v17 Go to Table of Contents 59 Bootloader 6 3 Baud Rate br Command Type Legacy Syntax br lt baud_rate_div_100 gt lt port gt Returns DONE Description This command sets the baud rate for the current port unless lt port gt is specified the port can be specified only in bootloader versions 45 and above The baud rate is specified as the desired baud rate divided by 100 in lt baud_rate div_100 gt The confirmation is printed in the new baud rate if the current port has been changed The baud rate is set on a per port basis Port 0 Secondary serial port 1 Primary serial port 2 Auxiliary serial port 1 3 Auxiliary serial port 0 4 USB Examples br1152 lt CR gt DONE at baud 115 200 br96 2 lt CR gt DONE at current baud but port 2 is set to 9600 Go to Table of Contents 60 6 4 Baud Store bs Command Type Legacy Syntax bs Returns DONE Description Bootloader This command will commit the current baud rates to non volatile memory This command was removed from bootloader versions 44 and above Instead the write configurations command wc is used Example bs lt CR gt DONE Go to Table of Contents 61 6 5 Hardware Version hv Command Type Legacy Syntax hv Returns Device hardware revision Description This command prints th
13. ten Examples id lt CR gt 38mm 47 id lt CR gt 100mm 28 Go to Table of Contents 29 v10 5 15 Initialize Aperture in Command Type Legacy Syntax in Returns DONE Description This command initializes the aperture motor and position This opens up the aperture to its minimum f number maximum opening This position is then set as the zero position for all subsequent aperture movement commands This is required before any of the aperture movement commands can be used as driving the aperture motor too far without knowing its position could damage the aperture mechanism The library prevents you from issuing aperture movement commands unless the position has first been initialized with this command Example in lt CR gt DONE Go to Table of Contents 30 v10 5 16 Image Stabilization is Command Type Legacy New Syntax is 0 1 Returns DONE Description Legacy Up to version 17 of the library this command turns on the image stabilization function of the lens This command blocks until any character is input into the device or power is removed so no other commands can be issued while it is active New Version 18 of the library introduces the ability to turn this function on or off as a background process In most cases lenses with image stabilization will already have the function active without needing this command In that case image stabilization should be turned on or off using the swit
14. to the fully closed position The number of steps in 1 4 stops that the aperture actually moved is given in lt signed num_steps gt The final position is given in lt f_number gt as the lens f number times ten Example mc lt CR gt DONE14 216 Go to Table of Contents 39 v10 5 25 Move Focus Incremental mf Command Type Legacy Syntax mf lt signed_counts gt Returns DONE lt signed_num_counts gt lt flag gt Description This command makes the focus mechanism move incrementally the number of counts specified in lt signed_counts gt If the number specified is positive then the focus moves towards the infinity position If the number is negative then the focus moves towards the zero position If the number of counts specified is out of range the mechanism will move as far as it can lt signed_num_counts gt is the actual number of counts moved and lt flag gt is 1 if the lens reports having hit a stop 0 if it hasn t Note that some lenses do not return a until the second time the stop is hit Examples mf100 lt CR gt DONE100 0 mf 50 lt CR gt DONE 50 0 Go to Table of Contents 40 v10 5 26 Move Focus to Infinity mi Command Type Legacy Syntax mi Returns DONE lt signed_num_counts gt lt flag gt Description This command moves the lens focus to the infinity position The actual number of counts moved as reported by the lens encoder is given in lt signed_num_counts gt lt flag g
15. Canon EF 232 Library User Manual BIRGER engineering 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 Table 2 Bootloader Command Quick Reference un unnnnnrirrrrrrorrrrnrnrrnrnn 7 3 General Notes on Using the Library cccccccccscssssssscsssssssccssscsseseeees 8 3 4 Mapped Absolute Focus Positioming ssccssssccssrrcessscccssseccssssessseseeeess 9 BS FOCUS DI a i i EEA A E T EEES 9 Go to Table of Contents 3 5 20 Lens Presence DP eedscssccdencsecsedssaccasesscasbedetsesedssdcasssdcdsecacesccssbudstsessceusdussdecssoveccuss 35 5 39 Set Spontaneous Responses SI crsssccssssecssssecsssscsessssssssssssssssssssssssssssssoers 54 5 40 Short Version String CVS sssdicsediccadecs sdecesedesedsess vcSecsccbsssuetscdecostacssdsedetescsessccssascoues 55 6 13 Long Version String Vin cccccccssssssssccccccccesssssvsccsccscceccesesecssccssescescscsesscsesscces 70 6 14 Short Version String V8 ssscsssscscccsecccssscsacsecssscsasssctoedeceocsscsscedesesedesscssasac ssssssusess 71 6 15 Write Configurations to EEPROM WC ccccccccssssssssscsscesssssssscssccscscesseseseces 72 6 16 XModem Firmware Download Xm ccccccccssssssssccsccscssssssvsssccceccescceesscsceesecs 73
16. 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 amp 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 amp 3 9 3 Focal Length and Aperture Range Status Format lt focal_length gt mm f lt min_f gt lt num_stops gt f lt max_f gt Where lt focal length gt is a decimal number for the current focal length in millimeters lt min f gt is a decimal number for the current minimum f number times ten lt num_stops gt is a decimal number for the number of 4 stops available and lt max_f gt 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 RAO is input 0 output 1 input 1 Port RA1 is input 0 output 1 input 2 Port RAO 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
17. actly 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
18. ch on the lens barrel Lenses that use full time manual focus such as the Canon EF 85mm f 1 2 L II USM need to have this turned on or they will not be able to be focused manually Examples isQ lt CR gt DONE isl lt CR gt DONE Go to Table of Contents 31 v16 5 17 Learn Absolute Focus Range Detect Lens la Command Type New Syntax la lt options 0 1 2 gt Returns DONE LA Description This command learns the focus range of the lens for the servo focus routine and also for any legacy commands in a single step No other lens movement commands can be issued while this command is in progress This command does not block so other commands that don t require lens communications can be issued while the lens is focusing A confirmation will be emitted by the device when the lens has completed focusing The servo focusing and mapped focus range will not function unless the lens focus range is learned This command can also be supplied with an argument that starts the lens detection process at different stages Option 0 Same as LA without arguments learn the lens focal range 1 Resynchronize with the lens 2 Re detect and resynchronize with the lens Examples la lt CR gt DONE LA lal lt CR gt DONE LA la2 lt CR gt DONE LA Go to Table of Contents 32 v18 5 18 Cached Extended Lens Status Ic Command Type New Syntax lc Returns lt focal_length gt mm f lt min_f gt lt num_stops
19. e Legacy Syntax pl 0 1 Returns Current setting Description This command does not perform any function It is included for legacy compatibility only Examples pll lt CR gt 1 plO lt CR gt 0 Go to Table of Contents 47 v16 5 33 Set Response Modes rm Command Type Legacy New Syntax rm lt verbose 0 1 gt lt new 0 1 gt Returns OK or 0 Description This command is used to set the response modes The first argument can be 0 or 1 representing terse mode or verbose mode respectively In verbose mode all characters sent to the device are echoed back out and most commands return confirmations and full status strings In terse mode no characters are echoed and command responses are limited to error codes for legacy behavior The second argument is optional if not supplied it defaults to 0 and indicates the protocol mode legacy 0 or new 1 Legacy mode maintains protocol compatibility with libraries version 15 and earlier The response modes are set on a per port basis the change being effective for the port over which the command is sent Examples rm0 1 lt CR gt OK rm0 0 lt CR gt 0 Go to Table of Contents 48 v18 5 34 Set EEPROM Byte se Command Type New Syntax se lt byte_number gt lt value gt Returns DONE Description This command will temporarily change an EEPROM setting The setting is not actually committed to non volatile memory with this command a
20. e command prompt to appear and a setting of 1 turns the prompt off When the prompt is on a single greater than symbol is printed as a prompt whenever the device is ready to accept a command This setting is copied forward into the library when booted The factory setting is to have the prompt disabled The command prompt is enabled disabled on a per port basis the setting being active for the port over which the command is sent Example sp0 lt CR gt OK gt Go to Table of Contents 69 Bootloader 6 13 Long Version String vn Command Type New Syntax vn Returns Long version string Description This command prints the long version string for the device Example vn lt CR gt BEI Boot Executive v44 c 2008 Birger Engineering Inc Go to Table of Contents 70 Bootloader 6 14 Short Version String vs Command Type Legacy New Syntax VS Returns s lt module gt v lt version gt Description Legacy Prior to bootloader version 44 this command prints an extended version string New This command prints the short version string that describes the code currently executing This string is given with the identifier s followed by the short module ID in lt module gt followed by the letter v followed by the decimal revision number The bootloader will return BE as the module ID Example vs lt CR gt S BEV44 Go to Table of Contents 71 Bootloader 6 15 Write Configurations to
21. e hardware revision of the device Example hv lt CR gt 4 Go to Table of Contents Bootloader 62 Bootloader 6 6 Library Version lv Command Type Legacy Syntax Iv Returns Full library identity string Description This command prints the full library identification string of the library currently in memory This command can be used after a firmware download to verify that the new library was loaded and programmed correctly Example lv lt CR gt Canon EF 232 Library v17 Go to Table of Contents 63 Bootloader 6 7 Query Communications Port qp Command Type New Syntax qp Returns Port number Description This command prints the identification number of the port over which communications are occurring Port 0 Secondary serial port 1 Primary serial port 2 Auxiliary serial port 1 3 Auxiliary serial port 0 4 USB Example qo lt CR gt 4 Go to Table of Contents 64 Bootloader 6 8 Set Response Modes rm Command Type Legacy New Syntax rm lt verbose 0 1 gt lt new 0 1 gt lt port gt Returns OK or 0 Description This command is used to set the response modes The first argument can be 0 or 1 representing terse mode or verbose mode respectively In verbose mode all characters sent to the device are echoed back out and most commands return confirmations and full status strings In terse mode no characters are echoed and command responses are limit
22. ed to error codes for legacy behavior The second argument is optional if not supplied it defaults to 0 and indicates the protocol mode legacy or new Legacy mode maintains protocol compatibility with libraries version 15 and earlier The response modes set in the bootloader are copied forward into the library when the library is booted They can be committed to non volatile memory in the bootloader so that the desired settings are active when power is applied to the device The response mode is set on a per port basis the settings being active for the port over which the command is sent unless the third argument is specified only in bootloader versions 45 and above In order to emulate legacy behavior if the command protocol is set to legacy 0 then an automatic write of this parameter and consequently all other non volatile parameters occurs Port 0 Secondary serial port 1 Primary serial port 2 Auxiliary serial port 1 3 Auxiliary serial port 0 4 USB Examples rm0 lt CR gt 0 rm0 1 lt CR gt OK rm1 0 2 lt CR gt OK Go to Table of Contents 65 Bootloader 6 9 Escape from Port Routing routeesc Command Type New Syntax routeesc lt depth gt Returns Routing canceled Description This command is used to cancel port routing The depth of the route was previously assigned using the port routing command rt If the depth given in this command is less than or equal to the previously set depth the
23. ens Go to Table of Contents 13 4 Howto 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 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 lt CR gt 44 Go to Table of Contents 16 v10 5 2 Define Aperture da Command Type Legacy Syntax da Returns f lt min gt lt num_stops gt f lt ma
24. er 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 non blocking 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 1 4 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 1 4 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 1 4 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 ex
25. gt f lt max_f gt Description This command will print the extended lens status from cached information The status string is of the form outlined in Section 3 9 Cached information is updated periodically by the library if background querying is turned on see command sm If multiple devices are interfacing to the lens controller over multiple serial ports then this command should be used to retrieve status as it will avoid conflicts Example lc lt CR gt 38mm f47 21 f293 Go to Table of Contents 33 v18 5 19 Library Loaded Il Command Type New Syntax I Returns OK Description This command simply prints OK It can be used as a test to see if the device is executing library code or bootloader code The command does not exist in the bootloader and therefore will not work unless library code is being executed Example 11 lt CR gt OK Go to Table of Contents 34 v16 5 20 Lens Presence Ip Command Type New Syntax Ip Returns Oorl Description This command will indicate if a lens is currently connected or not It prints the number 0 when no lens is connected and 1 when a lens is connected Examples lp lt CR gt 0 lp lt CR gt 1 Go to Table of Contents 35 v16 5 21 Immediate Extended Lens Status ls Command Type New Syntax Is Returns lt focal_length gt mm f lt min_f gt lt num_stops gt f lt max_f gt Description This command will print the extended
26. hat bracket the current focus position not as the near and far focal distances as determined by the actual optics involved which are calculations based on the lens focal length aperture focusing distance and circle of confusion Examples fd lt CR gt 45cm 48cm fd lt CR gt 65535cm 65535cm Go to Table of Contents 24 v15 5 10 Fast Focus ff Command Type Legacy New Syntax ff lt position gt Returns DONE Description This command has been updated to use the servo focus routine The position supplied uses the legacy focus positioning which are encoder counts as reported by the lens with the applied offset set through the focus counter command sf Example ff1000 lt CR gt DONE Go to Table of Contents 25 v16 5 11 Focus Positions fp Command Type New Syntax fp Returns fmin lt fmin gt fmax lt fmax gt current lt current_pos gt Description This command will print the focus positions in raw encoder counts as reported by the lens The positions are reported as signed decimals and as they are raw encoder counts do not have the focus counter offset applied lt fmin gt is the zero position of the lens and is updated every time the lens is commanded to the zero stop with the mz command lt fmax gt is the infinity position of the lens and is updated every time the lens is commanded to the infinity position with the mi command Both positions are updated if the learn focus range la
27. n the routing will be canceled This command must be entered exactly as shown no white space is allowed Example routeesc 0 lt CR gt Routing canceled Go to Table of Contents 66 Bootloader 6 10 Setup Port Routing rt Command Type New Syntax rt lt dest_port gt lt depth gt Returns lt source_port gt lt gt lt dest_port gt lt depth gt Description This command redirects all communications from the current port to the port specified in lt dest_port gt lt depth gt is a number from 0 9 assigned to the connection solely as a reference tag to be used in the routing escape command Port 0 Secondary serial port 1 Primary serial port 2 Auxiliary serial port 1 3 Auxiliary serial port 0 4 USB Examples rt0 0 lt CR gt 1 lt gt 0 0 rt2 4 lt CR gt 1 lt gt 2 4 Go to Table of Contents 67 Bootloader 6 11 Serial Number sn Command Type Legacy Syntax sn Returns Device serial number Description This command prints the device serial number The serial number is used as an input to the firmware download command as an unlock code Beginning with bootloader version 45 the serial number is printed with leading zeros in a five digit field Example sn lt CR gt 01234 Go to Table of Contents 68 Bootloader 6 12 Suppress Prompt sp Command Type New Syntax sp 0 1 Returns DONE Description This command disables the command prompt A setting of 0 causes th
28. nd therefore if the device is given a bad setting that causes it to malfunction removing power will clear the condition The index of the byte to change is given in lt byte_number gt and the new value is given by lt value gt The index is given as a decimal number and the value is given as a hexadecimal number The commonly configured parameters are almost always available through other commands so this command is used to alter the remaining parameters These parameters are often low level timing configurations Contact Birger Engineering if your programming needs might require modification to these parameters Example se4 0 lt CR gt DONE Go to Table of Contents 49 v10 5 35 Set Focus Counter Offset sf Command Type Legacy Syntax sf lt count gt Returns OK Description This command sets the focus counter to mark the current lens focus position with the value specified For example moving the focus to the zero position using the mz command will yield the lens encoder position for the zero stop which will almost always be non zero Using this command with an argument of zero at that point allows you to mark that position as zero and then zero would be the position input to the focus absolute commands to return to that same position Example sf0O lt CR gt OK Go to Table of Contents 50 v16 5 36 Set GPIO sg Command Type New Syntax Sg lt port gt lt state gt Returns DONE Description
29. ns f number times ten Example mo lt CR gt DONE 21 35 Go to Table of Contents 43 v10 5 29 Move Focus to Zero mz Command Type Legacy Syntax mz Returns DONE lt signed_num_counts gt lt flag gt Description This command moves the lens focus to the zero position The actual number of counts moved as reported by the lens encoder is given in lt signed_num_counts gt lt flag gt is 1 if the lens reports having hit a stop 0 if it hasn t Note that some lenses do not return a 1 until the second time the stop is hit Example mz lt CR gt DONE 1246 1 Go to Table of Contents 44 v10 5 30 Print Aperture Position pa Command Type Legacy Syntax pa Returns lt pos gt f lt f_number gt Description This command prints the current position of the aperture lt pos gt is the absolute position given in 4 stops from the fully open position and lt f_number gt is the absolute position given as the lens f number times ten Example pa lt CR gt 5 54 Go to Table of Contents 45 v10 5 31 Print Focus Position pf Command Type Legacy Syntax pf Returns Signed focus position in encoder counts Description This command prints the current position of the focus mechanism given in encoder counts with the user s desired focus counter offset applied Examples pf lt CR gt 1247 pf lt CR gt 743 Go to Table of Contents 46 v16 5 32 Lens Power pl Command Typ
30. ny 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 por
31. om 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 lt CR gt 18mm 55mm dz lt CR gt 50mm 50mm Go to Table of Contents 20 v16 5 6 Servo Focus with Checksum eh Command Type New Syntax eh lt absolute_position gt lt checksum gt 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 lt CR gt eh1000 1 lt CR gt eh3fff c lt CR gt Go to Table of Contents 21 v16 5 7 Exit to Bootloader ex Command Type New Syntax gt 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
32. 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 lt CR gt r l In bootloader ex lt CR gt BEI Boot Executive v44 c 2008 Birger Engineering Inc In bootloader Go to Table of Contents 22 vli 5 8 Focus Absolute fa Command Type Legacy Syntax fa lt position gt Returns DONE lt rposition gt lt flag gt Description This command makes the focus mechanism move to the specified focus count position specified in counts moved in lt position gt If an input value would move the focus out of the legal range the value is rounded to the boundary i e min max count lt rposition gt is the actual position that the count has been moved to lt flag gt is 1 if the lens reports having hit a stop and 0 if it hasn t Note that some lenses do not return a 1 until the second time the stop is hit Examples fal00 lt CR gt DONE100 0 fa2000 lt CR gt DONE1759 1 Go to Table of Contents 23 v10 5 9 Focus Distance fd Command Type Legacy Syntax fd Returns lt near gt cm lt far gt cm Description The number is returned as two distances lt near gt the near distance and lt far gt the far distance both in centimeters where 65535 represents infinity Not all lenses return distance information This information corresponds to what the lens reports as the stops t
33. t is 1 if the lens reports having hit a stop 0 if it hasn t Note that some lenses do not return a 1 until the second time the stop is hit Example mi lt CR gt DONE246 1 Go to Table of Contents 41 v10 5 27 Move Aperture Incremental mn Command Type Legacy Syntax mn lt signed_steps gt Returns DONE lt num_signed_steps gt f lt f_number gt Description This command moves aperture mechanism the specified number of steps in the specified direction in 1 4 stops given by lt signed_ steps gt A positive step is a move towards the fully closed position and a negative step is a move towards the fully opened position If an input value would move the aperture out of the legal range the value is clipped to the boundary i e min max aperture lt num_signed steps gt is the actual number of steps the aperture was moved and lt f_number gt is the absolute position of the aperture after executing the move in the lens f number times ten Examples mn2 lt CR gt DONE2 54 mn 1 lt CR gt DONE 1 f 49 Go to Table of Contents 42 v10 5 28 Move Aperture to Opened Position mo Command Type Legacy Syntax mo Returns DONE lt signed_num_steps gt f lt f_number gt Description This command will move the aperture to the fully open position The number of steps in 1 4 stops that the aperture actually moved is given in lt signed num_steps gt The final position is given in lt f_number gt as the le
34. t 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
35. x gt 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 1 4 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 lt CR gt 28 28 320 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 lt far gt lt near gt lt encoder gt 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 lt far gt lt
Download Pdf Manuals
Related Search