Skip to main content

Openservo API

Posted in

Here is the documentation for the C openservo library wrapper.

There are numerous bugs, and corrections that have been made since this initial release. Expect version 0.3 soon!

** REMOVED WIN32 SUPPORT FOR NOW ** This code is being rewritten for better win32 abstraction.

Download Openservo Library here

The openservo wrapper consists of many layers of abstraction, making prtability
very easy.

All functions return >0 for success, and &lt0 for error.
The read functions all take a pointer to the data. You must initialise the
variable before passing it to the servo. Example::

int variable;
openservo_get_pos( adapter_number, servo_number, &variable);

More on the proper calling conventions below.

1) Openservo initialisation sequence

You must initialise the openservo before add an adapter in the library.
This will allow the code to initialise, and optionally scan all of the bus for
devices.

Example initialisation

//initialise openservo variables, allocate memory
openservo_init();

//add an adapter, you can optionally provide an argument which is the device
//sub adapter. Mainly for linux /dev/i2c-x convention
openservo_add_adapter("gumstix", 0);

for the function openservo_adapter_add, valid arguments are gumstix, win32par
windimax, lindimax and linpar. Each corresponding to the relevant driver.

Each adaper will be given an incrementing reference that is passed to select
the servo. The first adapter is 0, second 1 and so on.

Once initialised, and the adapters added, we will be ready to add servos to
the bus.

2) Servo addition sequence

There are two methods of adding servos to the library, automatically, and manually.

openservo_scan();

openservo_add_servo( adapter_nr, 0x10);

openservo_scan will scan the whole bus, on all adapters, storing
a list of all servos on the busses, and adding a servo to the adapter.

openservo_add_adapter can be used is you know the existing address of the servo
you just pass the adapter number, and the servo address.

3) Reading and writing to the servo

Reading and writing to the servo is very simple, requring the passing of the
adapter rquired, the servo to read/write, and the variable to hole the result.

Example:-

int var;
openservo_get_pos(adapter_no,servo_no, &var);
openservo_getcurrent(adapter_no, servo_no, &var);
openservo_getspeed(adapter_no, servo_no, &var);
openservo_getpwm(adapter_no, servo_no, &var);
openservo_setpos(adapter_no, servo_no, &var);

//writing to servo
openservo_start(adapter_no, servo_no);
openservo_stop(adapter_no, servo_no);
openservo_reset(adapter_no, servo_no);

4) Cleaning up, and closing library

To close the devices, and close all adapter, call

openservo_deinit(0);

5) Direct and indirect reading.

Set the read type. This detmines whether the data from the servo is read
directly, or returned from the struture values. You must use the
periodical world update functions to make this work

You can program each individual servo to either read directly, or from the
stored data. This is useful for motors which do not need much updating,
and wont waste bandwidth.

Valid values are
0 disable direct comms with servo (must specify valid servo number)
1 enable direct comms to the servo
2 disable all direct comms with all servos
3 enable direct comms to all servos (default)

openservo_config_read_direct(adapter_no, servo_no, mode);

6) World update functions

There are functions to allow all of the servo structures to be refreshed. This
is really only of use if you are using indirect reading functions, as the
data structures would not get referenced otherwise (unless you are reading/
writing directly to the servo structures)

openservo_world_update();
openservo_select_world_update();

world_update reads all data from the servos, this comproses of velocity, pwm
and position. THis is then stored in the data structures for reading indirectly

select_world_update will read only servos programmed to read indirectly.
This is primarily a bandwidth saving function.

7) Bootloader

You can also flash the openservo with new code. The functions below provide
the functionality to reflash an existing servo, or flash one in bootloader
mode.

openservo_flash(adapter_nr,servo_nr,"filename.hex");
openservo_reflash(adapter_nr,servo_nr,bootloader_addr, "filename.hex");

openservo_flash will flash a servo alreasy in bootloader mode. Provide
the address the servo resides at (normally 0x7f)

openservo_reflash will flash a device that is already on the bus, and has been
detected by the library. You need to provide the current servo address, and
also the address it will revert to when in bootloader mode
(normally 0x7f)

8) Configuration options

If you have a problem where the servos are not turning in consistant directions
you can set some configuration options for the servo.
Direct and indirect modes are described above.

openservo_configure( adapter_no, servo_no, mode, var );

Example

openservo_configure( 0, 0x10, REVERSE_SEEK, 1 ); //change reverse seek mode

other options are
DEADBAND //set the width of the deadband
TWI_ADDRESS
PID_PGAIN
PID_DGAIN
PID_IGAIN
MIN_SEEK
MAX_SEEK
CHECKED_TXN //Read/Write registers with simple checksum

Consult Openservo website for more details on configuration options

You can then save the registers

Download Openservo Library here