Bioloid Command Line Utility

The bioloid program is a command line program for communicating with devices on the bioloid bus.

Command Line Options

Usage: bioloid <option(s)>
  Send commands to bioloid devices

  -b, --baud=baud   Set the baudrate used
  -p, --port=name   Set the serial port to use
  -d, --debug       Enable debug features
  -h, --help        Display this message
  -v, --verbose     Turn on verbose messages

The default baud rate is 1000000. Passing in the debug flag will cause all packet data sent to and received from the bus to be printed.

# bioloid.exe -p com8 -d
Debug enabled
> servo 15 ping
W: 0000: FF FF 0F 02 01 ED                               ......
R: 0000: FF FF 0F 02 00 EE                               ......
servo 15 Response Received

Commands

action

Broadcasts an ACTION command on the bus. This will cause registered writes to be performed.

scan [numIds]

Scans the bus, by sending ping commands to the indicated devices. If numIds is not specified, then it is assumed to be 32. If numIds is less than 100, then addresses from 0 to numIds - 1, and 100 to 100 + numIds - 1 will be scanned. If numIds is greater than 100, then ids from 0 to numIds - 1 will be scanned. For devices that respond, The model number and version will be read and reported.

> scan
> scan
ID:  15 Model:    12 Version:    22
ID:  18 Model:    12 Version:    22

dev-types

Lists the device types that the program knows about.

> dev-types
servo      Model:    12 34 registers

quit

Exits from the program.

Device Commands

The following commands are sent to a partiular device, and are of the form:

device-type id command arguments

device-type reg

Prints the registers associated with this device-type.

> servo reg
Addr Size Min  Max Name
---- ---- ---  --- --------------------
0x00 ro 2          model
0x02 ro 1          version
0x03 rw 1   0  253 id
0x04 rw 1   0  254 baud-rate
0x05 rw 1   0  254 return-delay-time
0x06 rw 2   0 1023 cw-angle-limit
0x08 rw 2   0 1023 ccw-angle-limit
0x0b rw 1   0  150 high-limit-temp
0x0c rw 1  50  250 low-limit-voltage
0x0d rw 1  50  250 high-limit-voltage
0x0e rw 2   0 1023 max-torque-def
0x10 rw 1   0    2 status-level
0x11 rw 1   0  127 alarm-led
0x12 rw 1   0  127 alarm-shutdown
0x14 ro 2          down-calib
0x16 ro 2          up-calib
0x18 rw 1   0    1 torque-enable
0x19 rw 1   0    1 led
0x1a rw 1   0  254 cw-comp-margin
0x1b rw 1   0  254 ccw-comp-margin
0x1c rw 1   1  254 cw-comp-slope
0x1d rw 1   1  254 ccw-comp-slope
0x1e rw 2   0 1023 goal-position
0x20 rw 2   0 1023 moving-speed
0x22 rw 2   0 1023 max-torque
0x24 ro 2          present-position
0x26 ro 2          present-speed
0x28 ro 2          present-load
0x2a ro 1          present-voltage
0x2b ro 1          present-temp
0x2c rw 1   0    1 reg-instruction
0x2e ro 1          moving
0x2f rw 1   0    1 lock
0x30 rw 2   0 1023 punch

device-type id ping

Sends a PING command to the indicated device.

device-type id get register
device-type id get-raw register

Retrieves the named register from the device indicated by id. In the case of get the register will be formatted, whereas get-raw just returns the raw register value. There is a special register name called all which will cause all of the registers to be retrieved and printed.

> servo 15 get present-voltage
Read: 11.7 volts
> servo 15 get-raw present-voltage
Read:   117
> servo 15 get all
Addr Size Value           Name
---- ---- --------------- --------------------
0x00 ro 2 12              model
0x02 ro 1 22              version
0x03 rw 1 15              id
0x04 rw 1 1000000 baud    baud-rate
0x05 rw 1 0 usec          return-delay-time
0x06 rw 2 0 degrees       cw-angle-limit
0x08 rw 2 300 degrees     ccw-angle-limit
0x0b rw 1 70C             high-limit-temp
0x0c rw 1 6.0 volts       low-limit-voltage
0x0d rw 1 14.0 volts      high-limit-voltage
0x0e rw 2 1023            max-torque-def
0x10 rw 1 all             status-level
0x11 rw 1 OvLoad OvHeat   alarm-led
0x12 rw 1 OvLoad OvHeat   alarm-shutdown
0x14 ro 2 40              down-calib
0x16 ro 2 973             up-calib
0x18 rw 1 off             torque-enable
0x19 rw 1 off             led
0x1a rw 1 1               cw-comp-margin
0x1b rw 1 1               ccw-comp-margin
0x1c rw 1 32              cw-comp-slope
0x1d rw 1 32              ccw-comp-slope
0x1e rw 2 150 degrees     goal-position
0x20 rw 2 0.0 RPM         moving-speed
0x22 rw 2 1023            max-torque
0x24 ro 2 150 degrees     present-position
0x26 ro 2 0.0 RPM         present-speed
0x28 ro 2 CCW 0           present-load
0x2a ro 1 11.7 volts      present-voltage
0x2b ro 1 32C             present-temp
0x2c rw 1 off             reg-instruction
0x2e ro 1 0               moving
0x2f rw 1 0               lock
0x30 rw 2 32              punch

device-type id set register value
device-type id set-raw register value

Sets the value of a register. Set-raw sets the raw register value, whereas set takes the natural units of the register (degrees, volts, etc.)

> servo 15 set goal-position 200
> servo 15 set-raw goal-position 682

device-type id read-data offset numBytes device-type id rd offset numBytes

Issues the READ_DATA command to the inidcated device. The read data is formatted as hex bytes. Note that read-data may be abbreviated as rd.

> servo 15 read-data 0x1e 4
Read: 001e: AA 02 00 00                                     ....

device-type id write-data offset byte data device-type id wd offset byte data

Issues the WRITE_DATA command to the indicated device. The data must be formatted as a sequence of bytes. Note that write-data may be abbreviated as wd.

> servo 15 write-data 0x1e 0xaa 2

device-type id reg-write offset byte data device-type id rw offset byte data

Issues the REG_WRITE command to the indicated device. The data must be formatted as a sequence of bytes. Note that reg-write may be abbreviated as rw.

> servo 15 reg-write 0x1e 0xaa 2
> servo 18 reg-write 0x1e 0x00 1
> action

device-type id reset

Issues the RESET command to the indicated device. This resets all registers to factory defaults, including changing the ID.

> servo 15 reset

Register Definition Files

The register definitions for devices on the bioloid bus are specified using register definition files. These files are named reg-*.bld and all of the files which match this specification and that are found in the same directory as the bioloid executable will be read when the bioloid program starts. Comments are denoted using the # character,and blank lines are allowed.

Each line starts with a keyword. Supported keywords are DeviceType:, Model:, Register: and EndDeviceType.

DeviceType: string


                    This starts a new device. Each DeviceType: 
                        tag must have a matching EndDeviceType tag 
                        later in the file. The device type should be a simple
                        string with no embedded spaces.

Model: number


                    Identifies the model associated with this device type. 
                        This field isn't currently used, but will eventually be 
                        used for populating device data structures based on a 
                        bus scan.

Register: offset name numBytes mode min max fieldType


                    Specifies a register. The offset is the register 
                        offset in the device memory. The name field is used to
                        identity the register. The numBytes field can have 
                        values 1 or 2 to indicate 8-bit or 16-bit registers. The 
                        mode must be ro (read-only) or rw (read-write). The min, 
                        max, and field type are optional for read-only fields.
                    Valid field types are:
                    
                        Alarm (format only) Translates the bits from the
                            alarm byte and prints as many of Inst, OvLoad,
                            ChkSum, Range, OvHeat, AngLim, InVolt as applicable,
                            or None if none of the bits are set.
                        Angle - Translate to/from degrees (0-300) into 
                            the raw value (0-1023)
                        AngularVelocity - Translates to/from RPM (0-114) 
                            into the raw range (0-1023)
                        BaudRate - Translates to/from the baudrate into 
                            the divisor format.
                        Load (format only) - Translates the direction 
                            bit to CW or CCW, and leaves the 10-bit portion as a
                            raw number.
                        OnOff - Translates between on/off and 0/1.
                        RDT - Translates from microsends (0-508) to the 
                            raw value (0-254).
                        StatusRet - Translates to/from none, read, all into
                            0, 1, 2 respectively.
                        Temperature - Translates to/from degrees 
                            celcius into the raw value (temperature * 1).
                        Voltage - Translate to/from volts into the raw 
                            value (voltage * 10).

EndDeviceType


                    Terminates the device-type definition.

Building from source

Full source code for this utility is available, and building has been tested under windows and linux. To build it under windows will require cygwin. You'll need subversion, gcc, and make. make needs to be version 3.81 or later. To build the windows installer, you'll need to also install NSIS and add it to your PATH.

To install the source code, cd to the directory where you would like the projects tree to go to, and do the following:

    svn co http://svn.hylands.org/common http://svn.hylands.org/rules http://svn.hylands.org/bioloid projects

The above will retrieve a small set of files required to build the command line utility. To check out the full tree, use:

    svn co http://svn.hylands.org/ projects

To build, use

    cd projects/bioloid/cli
    make

To build the windows installer (windows only):

    make installer

Note that while cygwin is required to build under windows, the bioloid executable is a Win32 native app (i.e. doesn't require cygwin1.dll)

Under windows, the executable can be found in bin/mingw. Under linux, the executable can be found in bin/linux.

To build for the gumstix, you'll need to edit the projects/rules/mkEnv-gumstix.mk file and ensure that the MK_TOOLS_DIR and MK_CROSS_COMPILE are initialized properly for your build environment. To build, use the command:

    make MK_OS=gumstix

The reg-*.bld files are expected to be in the same directory as the executable.