OpenServo Version 3 development "-dev" TWI/I2C Protocol

The Version 3-dev is the beta OpenServo software with lots of new features.

NOTE: I2C (prounouce "eye-square-see") is the two-wire bidirectional protocol utilized by the OpenServo for communication with a master controller. The protocol was invented by Philips and they have protected this name. For this reason other manufacturers have adopted different names for the same protocol. Atmel calls I2C "two wire interface" (TWI). This document adopts the TWI abbreviation used by Atmel for the bidirectional communication protocol to the OpenServo.

OpenServo Data Registers

The OpenServo implements 48 status registers that can be read from a master controller to modify and monitor the state of the servo. These registers are read using the TWI-bus DATA READ cycle and written using the TWI-bus DATA WRITE cycle.

NOTE: The OpenServo source code is the best documentation regarding the definition of each data register. Please refer to the 'registers.h' file for specific definitions of each register.

Read Only Registers

Registers 0x00 thru 0x1F are read-only and cannot be modified by the master controller. These registers implement servo status values and flags that can be modified by commands.

Read/Write Registers

Registers 0x20 thru 0x37 are always read-write enabled and can be modified by the master controller. These values implement dynamic servo control such as positioning.

Read/Write Protected Registers

Registers 0x38 thru 0x3F are write protected in that they can only be written by the master controller when the write enable flag is set via the WRITE_ENABLE command. These registers implement configuration information and are normally only written to during initial configuration of the servo.

OpenServo Register Table

Address

Name

Type

Description

0x00

DEVICE_TYPE

Read Only

Device type - 1 = OpenServo device type

0x01

DEVICE_SUBTYPE

Read Only

Device subtype - 1 = OpenServo device subtype

0x02

VERSION_MAJOR

Read Only

Major version number of OpenServo software

0x03

VERSION_MINOR

Read Only

Minor version number of OpenServo software

0x04

FLAGS_HI

Read Only

Flags high byte

0x05

FLAGS_LO

Read Only

Flags low byte

0x06

TIMER_HI

Read Only

Timer high byte - incremented each ADC sample

0x07

TIMER_LO

Read Only

Timer low byte - incremented each ADC sample

0x08

POSITION_HI

Read Only

Servo position high byte

0x09

POSITION_LO

Read Only

Servo position low byte

0x0A

VELOCITY_HI

Read Only

Servo velocity high byte

0x0B

VELOCITY_LO

Read Only

Servo velocity low byte

0x0C

POWER_HI

Read Only

Servo power high byte

0x0D

POWER_LO

Read Only

Servo power low byte

0x0E

PWM_CW

Read Only

PWM clockwise value

0x0F

PWM_CCW

Read Only

PWM counter-clockwise value

0x10

VOLTAGE_HI

Read Only

Battery Voltage value high byte

0x11

VOLTAGE_LO

Read Only

Battery Voltage value low byte

0x12

CURVE_BUFFER

Read Only

Remaining curve buffer space

0x13

TEMPERATURE_HI

Read Only

Current temperature of the board high byte

0x14

TEMPERATURE_LO

Read Only

Current temperature of the board low byte

...

...

...

...

0x20

SEEK_HI

Read/Write

Seek position high byte

0x21

SEEK_LO

Read/Write

Seek position low byte

0x22

SEEK_VELOCITY_HI

Read/Write

Speed seek position high byte

0x23

SEEK_VELOCITY_LO

Read/Write

Speed seek position low byte

0x24

CURVE_DELTA_HI

Read/Write

Curve Time delta high byte

0x25

CURVE_DELTA_LO

Read/Write

Curve Time delta low byte

0x26

CURVE_POSITION_HI

Read/Write

Curve position high byte

0x27

CURVE_POSITION_LO

Read/Write

Curve position low byte

0x28

CURVE_IN_VELOCITY_HI

Read/Write

Curve in velocity high byte

0x29

CURVE_IN_VELOCITY_LO

Read/Write

Curve in velocity low byte

0x2A

CURVE_OUT_VELOCITY_HI

Read/Write

Curve out velocity high byte

0x2B

CURVE_OUT_VELOCITY_LO

Read/Write

Curve out velocity low byte

0x2C

CURVE_RESERVED

Read/Write

Curve reserved register

0x2D

GENERAL_CALL_GROUP_START

Read/Write

Start a batch of servos off at the same time

0x2F

BANK_SELECT

Read/Write

Bank Selection register

0x30

...

Read/Write protected

...

...

...

Read/Write protected

...

0x3F

...

Read/Write protected

...

OpenServo Banks

The OpenServo implements a paged bank register system for the address range 0x40-0x7F. This bank system allows the OpenServo to have banks*address range registers, allowing more scope for future features.

The bank pages are divided into different sections, read/write informational banks, and a read/write configuration bank. There is also another bank that allows for redirected register layouts.

Bank Layout

Page 0

Information registers

Page 1

Configuration banks

Page 2

Redirected register support

Page 0 definition

Address

Name

Type

Description

0x00

ALERT_STATUS

Read/Write

Contains the alert/emergency status flags register

0x01

BACKEMF_HI

Read Only

EMF speed output high byte

0x02

BACKEMF_LO

Read Only

EMF speed output low byte

Page 1 definition

Address

Name

Type

Description

0x00

TWI_ADDRESS

Read/Write Protected

TWI address of servo

0x01

PID_DEADBAND

Read/Write Protected

Programmable PID deadband value

0x02

PID_PGAIN_HI

Read/Write Protected

PID proportional gain high byte

0x03

PID_PGAIN_LO

Read/Write Protected

PID proportional gain low byte

0x04

PID_DGAIN_HI

Read/Write Protected

PID derivative gain high byte

0x05

PID_DGAIN_LO

Read/Write Protected

PID derivative gain low byte

0x06

PID_IGAIN_HI

Read/Write Protected

PID integral gain high byte

0x07

PID_IGAIN_LO

Read/Write Protected

PID integral gain low byte

0x08

MIN_SEEK_HI

Read/Write Protected

Minimum seek position high byte

0x09

MIN_SEEK_LO

Read/Write Protected

Minimum seek position low byte

0x0A

MAX_SEEK_HI

Read/Write Protected

Maximum seek position high byte

0x0B

MAX_SEEK_LO

Read/Write Protected

Maximum seek position low byte

0x0C

REVERSE_SEEK

Read/Write Protected

Reverse seek sense

0x0D

PWM_FREQ_DIVIDER_HI

Read/Write Protected

PWM frequency divider high byte

0x0E

PWM_FREQ_DIVIDER_LO

Read/Write Protected

PWM frequency divider low byte

0x0F

PWM_MAX

Read/Write Protected

maximum PWM frequency

0x10

ALERT_CURR_MAX_LIMIT_HI

Read/Write Protected

Current limit for alerts and throttling

0x11

ALERT_CURR_MAX_LIMIT_LO

Read/Write Protected

Current limit for alerts and throttling

0x12

ALERT_VOLT_MAX_LIMIT_HI

Read/Write Protected

Max Voltage limit

0x13

ALERT_VOLT_MAX_LIMIT_LO

Read/Write Protected

Max Voltage limit

0x14

ALERT_VOLT_MIN_LIMIT_HI

Read/Write Protected

Min Voltage limit

0x15

ALERT_VOLT_MIN_LIMIT_LO

Read/Write Protected

Min Voltage limit

0x16

ALERT_TEMP_MAX_LIMIT_HI

Read/Write Protected

Max Temperature limit

0x17

ALERT_TEMP_MAX_LIMIT_LO

Read/Write Protected

Max Temperature limit

0x1E

ALERT_CAUSES_INT

Read/Write Protected

Masked value for disabling certain interrupts.

0x1F

ALERT_ENABLE

Read/Write Protected

Masked value for disabling certain alerts

0x20

GENERAL_CALL_GROUP

Read/Write Protected

Which group this OpenServo will respond to on broadcast

0x21

BRAKE_STRENGTH

Read/Write Protected

How much to apply the brake when stopping

0x2A

EMF_COLLAPSE_DELAY

Read/Write Protected

How long to wait for EMF collapse in ms

0x2B

EMF_CHARGE_TIME

Read/Write Protected

How long do we charge the sampling caps in EMF detection (longer is not always better)

0x2C

STEP_MODE

Read/Write Protected

The mode to use for stepping the motor (Stepper motors only)

Page 2 definition

Address

Name

Type

Description

0x00-0x0F

REDIRECT_REGISTER

Read/Write

Programmable redirect register

0x10-0x1F

REDIRECTED_REGISTER

Read/Write

Programmable redirected register

Redirected registers TBC

OpenServo Commands

The OpenServo implements the following commands that can be sent by the master controller to enable certain operations of the servo. These commands are sent to the OpenServo using the TWI-bus COMMAND cycle.

NOTE: Please refer to the 'twi.h' file for specific definitions of each command.

Command

Name

Description

0x00...0x7F

reserved

Reserved for data addresses (msb = 0)

0x80

RESET

Reset microcontroller

0x81

CHECKED_TXN

Read/Write registers with simple checksum

0x82

PWM_ENABLE

Enable PWM to motors

0x83

PWM_DISABLE

Disable PWM to servo motors

0x84

WRITE_ENABLE

Enable write of read/write protected registers

0x85

WRITE_DISABLE

Disable write of read/write protected registers

0x86

REGISTERS_SAVE

Save read/write protected registers fo EEPROM

0x87

REGISTERS_RESTORE

Restore read/write protected registers from EEPROM

0x88

REGISTERS_DEFAULT

Restore read/write protected registers to defaults

0x89

EEPROM_ERASE

Erase the AVR EEPROM

0x8A

PWM_BRAKE_ENABLE

Enable the FET clamps on the motor when stopped. Uses lots of power!

0x8B

PWM_BRAKE_DISABLE

Disable the motor braking

...

...

...

0x91

CURVE_MOTION_ENABLE

Enable curve based motion

0x92

CURVE_MOTION_DISABLE

Disable curve based motion

0x93

CURVE_MOTION_RESET

Clear the curve buffer

0x94

CURVE_MOTION_APPEND

Append a new curve

0x95

GCALL_ENABLE

Enable General Call

0x96

GCALL_DISABLE

Disable General Call

0x97

GCALL_START_WAIT

Store the new position and wait for the start_move command

0x98

GCALL_START_MOVE

Start the syncro move

OpenServo TWI-bus Protocol

Before any data is transmitted on the TWI-bus, the slave device that should respond is addressed first. Slave addressing is always carried out with the first byte transmitted after the start condition. The TWI-bus configuration for the COMMAND, DATA WRITE and DATA READ cycles is shown below.

TWI-bus COMMAND Cycle

After the slave address with the read/write flag set to 0, an unlimited number of command bytes can be sent. Each command byte must have the address/command flag (most significant bit) set to 1. DATA WRITE/READ cycle can be entered by sending an address with the most significant bit set to 0.

TWI-bus DATA WRITE Cycle

After the slave address with the read/write flag set to 0, a data address is written with the address/command flag (most significant bit) set to 0. The address is latched. An unlimited number of data bytes can be written in one operation with the address being automatically incremented after each write. The address will wrap to 0x00 after address 0x7F is written. Data writing will continue until a TWI stop or start condition is set by the master.

TWI-bus DATA READ Cycle

After the slave address with the read/write flag set to 0, a data address is written with the address/command flag (most significant bit) set to 0. The address is latched. To read each data byte the master then sets a start condition and sends the slave address with the read/write flag set to 1 indicating data reads will follow. An unlimited number of data bytes can be read in one operation with the address being automatically incremented after each read. The address will wrap to 0x00 after address 0x7F is read. Data reading will continue until a TWI stop or start condition is set by the master.

OpenServo TWI-bus Checked Protocol

TBD

Return to Docs, Tools & Utilities

TWIProtocol-dev (last edited 2012-10-12 19:51:18 by localhost)