motor module arduino api manual - renesasrulz
TRANSCRIPT
Motor Module
Arduino API Manual
Renesas Electronics Corporation
1 / 119
Revision History
Rev. Date of issue
1.0 March 31, 2015 First edition
1.1 July 1, 2015 Updats controlInit(), sample programs
and serial specifications.
2 / 119
Table of Contents
1 Quick Start ..................................................................................................................... 4
1.1 Hardware Set-up ...................................................................................................... 4
1.2 Software Set-up ....................................................................................................... 5
1.3 Arduino Sample Programs ....................................................................................... 7
Speed control sample program ................................................................................... 7
Angle control sample program .................................................................................... 8
Angle control sample program with speed limit ....................................................... 9
2 Overview of the Control API ....................................................................................... 10
2.1 Purpose .................................................................................................................. 10
2.2 Features of the API ................................................................................................ 10
2.3 Definitions of Terms ............................................................................................... 10
2.4 Operating Model .................................................................................................... 10
2.5 Programing Procedure ........................................................................................... 13
2.6 Sample Programs .................................................................................................. 15
Sample program for angle control with multiple limitations .................................. 15
2.7 Synchronization of Multiple Motors ........................................................................ 16
Trigger function ........................................................................................................... 16
Programming procedure ............................................................................................ 16
Sample programs ........................................................................................................ 18
3 Control API Commands .............................................................................................. 21
3.1 Software Structure ................................................................................................. 21
3.2 Class Diagram ....................................................................................................... 21
3.3 Class List ................................................................................................................ 22
3.4 Description of Each Class ...................................................................................... 23
3.4.1 Root Class ..................................................................................................... 23
3.4.2 Module Class ................................................................................................. 25
3.4.3 Motor Cass .................................................................................................... 33
3.4.4 Serial Communication Class ..................................................................... 104
4 Serial Communication Specifications .................................................................... 107
4.1 Overview .............................................................................................................. 107
4.2 Applicable Communication Standards ................................................................. 107
4.3 Packet Specifications ........................................................................................... 108
4.4 Command Codes ................................................................................................. 109
5 Modules ....................................................................................................................... 114
5.1 Motor Modules ...................................................................................................... 114
3 / 119
5.1.1 DC Motor Module ......................................................................................... 114
4 / 119
1 Quick Start
1.1 Hardware Set-up
Table 1-1 lists the pieces of hardware to be used.
Table 1-1 List of Devices To Be Used
Figure 1-1 shows the set-up of the hardware.
1. Connect the PC and the Arduino with the USB cable.
2. Connect the interface board to the pin socket of the Arduino.
3. If the control board of the motor module and the motor are separated, connect the control
board and the motor with the cable that comes with the motor module.
Connect the I2C port (bus number 1) on the interface board and the DC motor module
with the I2C cable. Each I2C port has two conectors (4 pin and 5 pin), the functionality is
the same.
4. Connect the DC motor module and the power supply with the power cable. Use the
power supply at 5 to 24 V.
PC
Arduino (UNO is recommended)
Interface board
Motor module
DC power supply (5 to 24 V DC)
USB cable
I2C cable
Power cable
5 / 119
Figure 1-1 Hardware Set-up
1.2 Software Set-up
Download the Arduino library (Control.zip) from the website below.
http://japan.renesasrulz.com/pm_user_forum_japanese/default.aspx
6 / 119
Figure 1-2 Downloading the Library
Select Sketch Add .ZIP Library Select the downloaded file (Control.zip) You can
find “Control” in your library list.
Figure 1-3 Installing the Library
Download
7 / 119
1.3 Arduino Sample Programs
Speed control sample program
Shown below is a sample program that controls the speed by setting it to a constant value
of 60 rpm. The setup() function performs initialization and assignment of the motor, and uses
the setTargetSpeed command to set the speed to rotate it at a constant speed of 60 rpm.
The loop() function uses the getPresentSpeed command to obtain the present speed, and
transfers it to the PC through serial communication. Starting up the serial monitor of the
Arduino IDE displays the present rotational speed. As for rotational direction, the
counterclockwise direction viewed from the load side is positive.
The I2C address of the motor module is shown on the casing. This program uses 1 as the
bus number of the motor module, and 32 as the I2C address.
Sample1.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor class
void setup() {
Serial.begin(9600);
root.controlInit(); //Initializes Control API
motor.attach(1,32); //Assigns a motor module
motor.setTargetSpeed( 60.0 ); //Sets target rotational speed to 60rpm
}
void loop(){
float speed = motor.getPresentSpeed(); //Obtains present rotational speed [rmp]
Serial.println( speed );
8 / 119
}
Angle control sample program
Shown below is an angle control sample program that rotates the motor 10 turns (3600
degrees). It uses the setTargetAngle command to set the angle to rotate it 10 turns (3600
degrees). The loop() function uses the getPresentAngle command to obtain the present
angle and transfers it to the PC through serial communication. Starting up the serial monitor
of the Arduino IDE displays the present angle. Also, as for rotational direction, the
counterclockwise direction viewed from the load side is positive.
Sample2.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor class
void setup() {
Serial.begin(9600);
controlInit(); //Initializes Control API
motor.attach(1,32); //Assigns a motor module
motor.setTargetAngle( 3600.0 ); //Sets target angle to 3600 degree
}
void loop(){
float angle = motor.getPresentAngle(); //Obtains present angle [degree]
Serial.println( angle );
}
9 / 119
Angle control sample program with speed limit
Shown below is a sample program that rotates the motor 10 turns at a constant speed of
60 rpm. It uses the setMaxSpeed command to limit the maximum speed to 60 rpm, and uses
the setTargetAngle command to issue an angle instruction to rotate the motor 10 turns (3600
degrees).
Sample3.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor class
void setup() {
controlInit(); //Initializes Control API
motor.attach( 1 , 32 ); //Assigns a motor module
motor.setMaxSpeed( 60.0 ); //Sets maximum speed to 60 rpm
motor.setTargetAngle( 3600.0 ); //Sets target angle to 3600 degree
}
void loop(){
float speed = motor.getPresentSpeed(); //Obtains present speed[rpm]
float angle = motor.getPresentAngle(); //Obtains present angle[degree]
}
10 / 119
2 Overview of the Control API
2.1 Purpose
The purpose of this API is to easily control a motor and the like.
2.2 Features of the API
The features of this API are as follows:
Easy-to-use and understand command system controllable with, for example, an
instruction to rotate at 180 degrees
Class structure to easily develop robots, etc. that use multiple modules
Capable of synchronizing the operational timing of multiple muddles
Inter-module serial communication protocol with a standardized command code system
Available not only for Arduino and Raspberry Pi but also for devices with an I2C bus
2.3 Definitions of Terms
API Application Programming Interface.
Control API This API. It can easily control modules such as a motor and a sensor.
PWM Pulse Width Modulation.
Module Physical or logical unit controlled by this API. Most generally, one motor is
treated as one physical module, but a group of multiple modules can be
treated as a logical module. One I2C address is allocated to one physical
module.
2.4 Operating Model
The control software implemented in the control board of the motor module and the API
that executes the software allow you to easily control the motor using simple commands.
This section explains how to use commands, using the operating model of the motor module
in Figure 2-1. The motor module controls the motor according to register values: the internal
target values (Target Value (Active)) and the maximum values (Max Value (Active)). You can
control the motor by using the Control API to change these register values. The information
on the state of the motor, such as speed and angle, is always updated in the registers for
11 / 119
present values (Present Value), and you can find out the state of the motor by obtaining these
values through the Control API.
Figure 2-1 Operating Model of the Motor Module
Any one of the following can be specified as a target value (Target Value (Active)) to control
the motor module: angle, rotational speed, torque, current, voltage, and PWM duty ratio. For
example, a 3600-degree rotation (10 turns) is immediately performed by using the
setTargetAngle(3600) command to specify the target angle, as shown in Figure 2-2.
You can obtain the following as the present values (Present Value) of the motor module:
angle, rotational speed, torque, current, voltage, and PWM duty ratio. For example, to obtain
the present angle and the present speed, use the getPresentAngle command and the
setPresentSpeed command, respectively.
As for the rotational direction of the motor, the counterclockwise direction viewed from the
load side is positive, as shown in Figure 2-3 (CCW: counter-clockwise).
12 / 119
Figure 2-2 Timing Chart of Angle Control
Figure 2-3 Rotational Direction of the Motor
When any one of the following is specified as a target value, other target values are ignored
or automatically calculated: angle, speed, acceleration, torque, current, voltage, and PWM
duty ratio. For example, if a target angle is set, as shown with a dotted line in the lower part
of Figure 2-2, a target speed is automatically calculated according to the difference between
the target angle and the present angle. Within the module, target values are automatically
calculated in the following order: target angle, target speed, target torque, target current,
target voltage, and duty ratio. Also, if a target speed is set, a target value for angle is ignored,
and target values are automatically calculated in the following order: target speed, target
torque, target current, target voltage, and duty ratio.
Also, you can limit the maximum of each target value to control operation. For example, in
order to rotate the motor 3600 degrees (10 turns) at 60 rpm, use the setMaxSpeed(60)
command to limit the maximum of the rotational speed to 60 rpm, and then use the
setTargetAngle(3600) command to perform a 3600-dgree (10-turn) rotation. In this case, the
target rotational speed automatically calculated from the difference between the target angle
and the present angle will become more than 60 rpm, but rotation will be performed at 60
rpm for a while because the maximum speed is limited to 60 rpm, as shown with a solid line
in the lower part of Figure 2-4. Then, when the target rotational speed automatically
13 / 119
calculated from the difference between the target angle and the present angle becomes less
than 60 rpm, the motor is controlled so that it rotates at that rotational speed. Immediately
after a target value is set by using a setTarget command, the motor starts rotating; therefore,
a setMax command to limit a maximum value must be executed before a setTarget command
to set a target value. By using setMax commands, you can limit multiple target values. For
example, it is possible to limit both the maximum speed and the maximum torque.
Figure 2-4 Timing Chart of Control with Limitation
2.5 Programing Procedure
Figure 2-5 shows a typical procedure for programming with the Control API. First, use the
controlInit command to initialize communication functions, etc. Then, use the motor.attach
command to assign the module. These are initialization and initial setting and must be
performed only once. After that, use setMax and setTarget commands to specify maximum
values and target values to control operation. Also, you can obtain the present values of the
motor by using getPresent commands.
14 / 119
Figure 2-5 Programming Procedure
15 / 119
2.6 Sample Programs
Sample program for angle control with multiple limitations
Shown below is a sample program that rotates the motor 90 degrees at a current of 2A or
less, an effective voltage of 10V or less, and a speed of 60 rpm or less.
Sample4.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor class
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1 , 32 ); //Assigns a motor module
motor.setMaxSpeed( 60.0 ); //Sets maximum rotational speed to 60 rpm
motor.setMaxCurrent( 2.0 ); //Sets maximum current to 2 A
motor.setMaxVoltage( 10.0 ); //Sets maximum voltage to 10 V
motor.setAngleDeadband( 10.0 ); //Sets deadband angle to 10 degree
motor.setTargetAngle( 90.0 ); //Sets target angle to 90 degree
}
void loop(){
float speed = motor.getPresentSpeed(); //Obtains present speed[rmp]
float angle = motor.getPresentAngle(); //Obtains present angle[degree]
}
16 / 119
2.7 Synchronization of Multiple Motors
Trigger function
When controlling multiple modules, you may need to synchronize them. For example, to
move forward a two-wheel robot that has a separate motor for each of the left and right
wheels, the motors for the left and right wheels must start rotating simultaneously; otherwise,
the robot cannot move in a straight line. In order to synchronize the operational timing of
multiple modules, this API has the function of using a trigger to enable a reserved command.
While it is possible to immediately set a target value or a maximum value for the motor, it is
also possible to delay the setting of values until a trigger is received. Also, present values of
the motor, such as angle, speed, torque, current, and voltage, can be read not only
immediately, but also one by one from registers after they are temporarily stored in the
registers when a trigger is received.
Programming procedure
Figure 2-6 shows a program procedure to synchronize operations of multiple motors by
using a trigger. First, use the controlIinit command and the motor.attach command to perform
initialization. Then, execute setMax and setTarget commands with a trigger ID specified as
an argument. If a trigger ID is specified, the target value or the maximum value is not
immediately applied and is temporarily stored in a register as a reserved value shown in
Figure 2-1 (Max Value (Reserved) or Target Value (Reserved)). Then, when the said trigger
ID is made effective by using the controGlobalTrigger command, the reserved target value
or maximum value is applied simultaneously to control. The capturePresentValues command
stores, in a register, a snapshot of present values, such as angle, rotational speed, torque,
current, and voltage. After the capturePresentValues command is executed with a trigger ID
specified, the latest values (Present Value) are stored in registers (Captured Value) at the
moment when the controGlobalTrigger command is used to make the said trigger ID effective.
Then, the values stored in the registers (Captured Value) can be obtained by using the
getPresent command with its argument set to 1.
17 / 119
Figure 2-6 Program Procedure to Move Multiple Motors Simultaneously
Figure 2-7 shows timing charts of the following cases: immediately starting the two motor
modules without using a trigger; and starting them simultaneously by using a trigger. If
motor1.setTargetAngle(90) and motor2.setTargetAngle(90) are executed in this order, the
motors start separately at the same interval that separates the transfers of the commands.
motor1. Meanwhile, if motor1.setTargetAngle(90,1), motor2.setTargetAngle(90,1), and
controlGlobalTrigger(1) are executed in this order, the settings of the motors are enabled
simultaneously when the trigger command is received, so that the two motors can start at the
same time.
18 / 119
Figure 2-7 Timing Charts of Immediate Operation and Triggered Operation
Sample programs
Sample program that starts multiple motors simultaneously
Shown below is a program that simultaneously rotates two motors 200 degrees. The
program specifies settings separately for motor1 and motor2, and then applies the settings
simultaneously when issuing the controlGlobalTrigger command.
[Note] The trigger feature is implemented only for busNumber 2.
19 / 119
Trigger.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor1,motor2; //Declares motor class
void setup() {
root.controlInit(); //Initializes Control API
motor1.attach( 2 , 32 ); //Assigns two motor modules
motor2.attach( 2 , 40 );
motor1.setTargetAngle( 200.0, 1); //Sets target angle to 200 degree
motor2.setTargetAngle( 200.0, 1); //Waits for trigger (ID=1)
root.controlGlobalTrigger(1); //Issues trigger (ID=1)
}
void loop(){
float angle1 = motor1.getPresentAngle(); //Obtains present angle[degree]
float angle2 = motor2.getPresentAngle();
}
Sample program that obtains the states of multiple motors at the same time point
Shown below is a program that obtains the angles of two motors at the same time point.
The program causes the motors to transfer their respective present values (Present Value)
to registers (Captured Value) when issuing the controlGlobalTrigger command, so as to retain
the values given at the same time point. Then, it uses the getPresentAngle commands with
their arguments set to 1 to read the values of the registers (Captured Value) one by one.
20 / 119
Capture.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor1,motor2; //Declares motor class
void setup() {
root.controlInit(); //Initializes Control API
motor1.attach( 2 , 32 ); //Assigns two motor modules
motor2.attach( 2 , 40 );
motor1.setTargetAngle( 500.0 ); //Sets target angle
motor2.setTargetAngle( 200.0 );
}
void loop(){
motor1.capturePresentValues( 1 ); //Sets triggerID for capturing
motor2.capturePresentValues( 1 );
control.controlGlobalTrigger( 1 ); //Trigger
float angle1 = motor1.getPresentAngle( 1 ); //Obtains captured angle[degree]
float angle2 = motor2.getPresentAngle( 1 );
}
21 / 119
3 Control API Commands
This section describes the commands of the Control API.
3.1 Software Structure
Figure 3-1 shows the software structure of the Control API. The Control API has a low level
API for serial communication with modules via the interface board, in addition to APIs that
allow easy control of motors and sensors.
Figure 3-1 Sofware Structure
3.2 Class Diagram
Figure 3-2 shows a class diagram of the Control API. The Motor module class and the
Sensor module class, each of which consists of commands specific to each module, are
inherited by the Module class, which consists of commands common to modules; also, the
Module class is inherited by the Serial Communication class, which establishes
communication with modules. Moreover, the Root class and the Composite Module class are
available as a class for summarizing multiple module classes; the Root class consists of
commands, such as for initialization of the Arduino and peripheral functions of the interface
board and for triggers to all modules, and the Composite Module class consists of commands
common to modules consisting of multiple motors such as a robot. A class for each
22 / 119
application such as a two-wheel robot and a drone is inherited by the Composite Module
class.
Figure 3-2 Class Diagram
3.3 Class List
Table 3-1 lists the classes.
Table 3-1 Class List
Class Description
Root Class consisting of commands for initialization, triggers,
etc.
Module Class consisting of commands common to modules
Motor Class consisting of commands to motors
Sensor Class consisting of commands to sensors
23 / 119
Battery Class consisting of commands to a battery
Serial Communication Class consisting of commands for communication with
modules
Composite Module Class consisting of common commands for operating
multiple modules
3.4 Description of Each Class
3.4.1 Root Class
The Root class consists of commands, such as for initialization of communication functions
of the Arduino and the interface board and for triggers to all modules.
Table 3-2 List of the Root Class Methods
Method Description
uint8_t controlInit( uint8_t mode=0 ) Initializes the Arduino and
peripheral functions of the
interface board
uint8_t controlGlobalReset( void ) Resets all modules
uint8_t controlGlobalTrigger( uint8_t
tiggerID=0 )
Issues a trigger
uint8_t controlEmergencyStop( void ) Brings all modules to an abrupt
stop
Methods
controlInit
uint8_t controlInit( uint8_t mode )
Initializes communication functions of the Arduino and the interface board.
Parameters
mode : Initialization mode
0(default): Initializes I2C and SPI ports.
1: Initializes I2C ports.
2: Initializes SPI ports.
24 / 119
Returns
0: Execution succeeded 1: Execution failed
controlGlobalTrigger
uint8_t controlglobalTrigger( int8 tiggerID=0 )
Issues a trigger to all modules.
Parameters
triggerID : The number of the trigger to be issued (1 to 7)
Returns
0: Execution succeeded 1: Execution failed
controlGlobalReset
uint8_t controlglobalReset( void )
Resets all modules.
Returns
0: Execution succeeded 1: Execution failed
controlEmergencyStop
uint8_t controlemergencyStop( void )
Brings all modules to an abrupt stop.
Returns
0: Execution succeeded 1: Execution failed
25 / 119
3.4.2 Module Class
The Module class consists of commands common to modules, such as for reset and module
ID acquisition.
Table 3-3 List of Member Variables of the Module Class
Table 3-4 List of the Methods of the Module Class
Category Method Name Description
Assignment
uint8_t attach(uint8 busNumber, uint8
address, uint8 subAddress=0) Assigns a module
uint8_t isAttached( void ) Confirms the assignment of
the module
uint8_t detach( void ) Cancels the assignment of
the module
Status check
uint8_t ping( void ) Checks response
uint8_t getStatusFlag( void ) Reads the status flag
uint8_t getErrorCode( void ) Reads the error code
Reset
uint8_t reboot( void ) Performs reboot
uint8_t factoryReset( void ) Reads factory default
parameter settings
Communication
setting
uint8_t setTimeoutLimit(uint8
miliSecond)
Sets the communication
timeout time
uint8_t getTimeoutLimit( void ) Reads the communication
timeout time
uint8_t changeAddress( uint8_t
newAddress)
Changes the module
address
Type Variable Name Description
uint8 busNumber Bus number
uint8 address Module address on a bus
uint8 subAddress
Subaddress within the module
(e.g., for controlling two motors with one
microcontroller)
int8 statusFlag Status flag
26 / 119
Module
information
uint8_t getModuleType(char *data) Reads information on the
module type
uint8_t getModelID(char *data) Reads the model ID
uint8_t getFirmwareVersion(char
*data)
Reads the firmware version
information
uint8_t getSerialID(char *data) Reads the serial ID
LED uint8_t setLED(uint8_t value) Operates the LED
uint8_t getLED( void ) Reads the state of the LED
Member variables
busNumber
Bus number.
Table 3-5 Bus number
Value Meaning
0 Arduino I2C bus
1 Interface board I2C bus number #1
2 Interface board I2C bus number #2
3 Interface board I2C bus number #3
4 Interface board I2C bus number #4
5 Interface board RS485 bus
address
Module address on a bus (I2C address if the module is connected to an I2C bus)
subAddress
Subaddress within the module.
27 / 119
Figure 3-3 Subaddress
statusFlag
Flag indicating the status of the module
Table 3-6 Module Status Flag
Bit Position Meaning
1st bit Whether or not there is a response from the module
Ack/Nack
Whether commands are valid or invalid
Whether arguments are valid or not
Whether or not there is an error
Whether or not target values have been reached
…etc., to be determined
2nd bit
3rd bit
4th bit
5th bit
6th bit
7th bit
8th bit
Methods
Assignment
Attach
uint8_t attach( uint8_t busNumber, uint8_t address, uint8_t subAddress )
I2C Cable
SubAddress=2
SubAddress=1Address=10 Address=10
I2C Cable
Motor Module
Motor Module
One motor in a moduleTwo or more motors
in a module
28 / 119
Assigns a module.
Parameters
busNumber : Bus number (Refer to Table 3-5)
address : I2C address
subAddress : Subaddress within the module
Returns
0: Execution succeeded 1: Execution failed
isAtached
uint8_t isAttached( void )
Confirms the assignment of the module.
Returns
0: Not assigned 1: Assigned
detach
uint8_t detach( void )
Cancels the assignment of the module.
Returns
0: Execution succeeded 1: Execution failed
Status check
ping
uint8_t ping( void )
Checks a response.
Returns
0: Execution succeeded 1: Execution failed
getStatusFlag
uint8_t getStatusFlag( void )
29 / 119
Obtains the status flag of the module.
Returns
Status flag (Refer to Table 3-6)
getErrorCode
uint8_t getErrorCode( void )
Obtains the error code.
Returns
Error number
Reset
reboot
uint8_t reboot( void )
Reboots the module (reset).
Returns
0: Execution succeeded 1: Execution failed
factroryReset
uint8_t factoryReset( void )
Returns the internal module parameters to the factory default settings.
Returns
0: Execution succeeded 1: Execution failed
Communication setting
setTimeoutLimit
uint8_t setTimeoutLimit( uint8 miliSecond )
Sets the communication timeout time.
If there is a failure to receive data from the master side within the specified timeout time, the
30 / 119
motor will be stopped.
Parameters
millisecond : Timeout time (ms)
Returns
0: Execution succeeded 1: Execution failed
getTimeoutLimit
uint8_t getTimeoutLimit( void )
Reads the communication timeout time.
Returns
Timeout time (ms)
changeAddress
uint8_t changeAddress( uint8_t newAddress )
Changes the module address.
Parameters
newAddress : Module address
Returns
0: Execution succeeded 1: Execution failed
Module information
getModuleType
uint8_t getModuleType( char *data )
Reads information on the module type such as motor and sensor.
Parameters
*data : Pointer to the location where the module type is stored
Returns
31 / 119
0: Execution succeeded 1: Execution failed
getModelID
uint8_t getModelID( char *data )
Reads the model ID.
Parameters
*data : Pointer to the location where the model ID is stored
Returns
0: Execution succeeded 1: Execution failed
getSerialID
uint8_t getSerialID( char *data )
Reads the serial ID.
Parameters
*data : Pointer to the location where the serial ID is stored
Returns
0: Execution succeeded 1: Execution failed
getFirmwareVersion
uint8_t getFirmwareVersion( char *data )
Reads the firmware version information.
Parameters
*data : Pointer to the location where the firmware version is stored.
Returns
0: Execution succeeded 1: Execution failed
LED
32 / 119
setLED
uint8_t setLED(uint8_t value)
Turns on and off and blinks the LED.
Parameters
value : LED status 0: Off, 1: On, 2: Blink, 255: Module default operation
Returns
0: Execution succeeded 1: Execution failed
getLED
uint8_t getLED( void )
Reads the LED status.
Returns
LED status 0: Off, 1: On, 2: Blink, 255: Module default operation
33 / 119
3.4.3 Motor Cass
The Motor class consists of commands for operating a motor.
Table 3-7 List of the Methods of the Motor Class
Category Method Name Description
Angle control
uint8_t setTargetAngle(float angle, int
triggerID=0)
Sets the absolute target
angle
uint8_t addTargetAngle(float angle, int
triggerID=0)
Sets the relative target
angle
float getTargetAngle(int
fromReserved=0) Reads the target angle
float getPresentAngle(int
fromCapture=0) Reads the present angle
uint8_t resetAngle( float angle=0 )
Initializes the present angle
to the value of the
parameter ‘angle’
uint8_t setMaxAngle(float angle, int
triggerID=0)
Sets the maximum angle in
the rotational range
float getMaxAngle( void ) Reads the maximum angle
uint8_t setMinAngle(float angle, int
triggerID=0)
Sets the minimum angle in
the rotational range
float getMinAngle( void ) Reads the minimum angle
uint8_t setAngleToSpeedGainP( float
gain )
Adjusts the proportional
gain for angle control
float getAngleToSpeedGainP( void ) Reads the proportional gain
for angle control
uint8_t setAngleToSpeedGainI( float
gain )
Adjusts the integral gain for
angle control
float getAngleToSpeedGainI( void ) Adjusts the integral gain for
angle control
uint8_t setAngleToSpeedGainD( float
gain )
Adjusts the derivative gain
for angle control
float getAngleToSpeedGainD( void ) Adjusts the derivative gain
for angle control
34 / 119
uint8_t setAngleDeadband(float angle)
Adjusts the deadband
(compliance margin) for
angle control
float getAngleDeadband( void )
Reads the dead band
(compliance margin) for
angle control
uint8_t setAnglePunch( float angle )
Adjusts the punch for angle
control (based on the input
angle)
float getAnglePunch( void )
Reads the punch for angle
control (based on the input
angle)
Speed control
uint8_t setTargetSpeed(float
speedRPM , int triggerID=0) Sets the target speed
float getTargetSpeed(int
fromReserved=0) Reads the target speed
float getPresentSpeed(int
fromCapture=0) Reads the present speed
uint8_t setMaxSpeed(float speedRPM,
int triggerID=0)
Sets the maximum speed
(speed limit)
float getMaxSpeed( void ) Reads the maximum speed
(speed limit)
uint8_t setMaxAcceleration(float
AccelerationRPM/s, int triggerID=0)
Sets the maximum
acceleration (acceleration
limit)
float getMaxAcceleration( void )
Reads the maximum
acceleration (acceleration
limit)
uint8_t setSpeedToTorqueGainP( float
gain )
Adjusts the proportional
gain for speed control
float getSpeedToTorqueGainP( void ) Reads the proportional gain
for speed control
uint8_t setSpeedToTorqueGainI( float
gain )
Adjusts the integral gain for
speed control
35 / 119
float getSpeedToTorqueGainI( void ) Reads the integral gain for
speed control
uint8_t setSpeedToTorqueGainD( float
gain )
Adjusts the derivative gain
for speed control
float getSpeedToTorqueGainD( void ) Reads the derivative gain
for speed control
Torque control
uint8_t setTargetTorque(float
TorqueNm, int triggerID=0) Sets the target torque
float getTargetTorque(int
fromReserved=0) Reads the target angle
float getPresentTorque(int
fromCapture=0) Reads the present torque
uint8_t setMaxTorque(float TorqueNm,
int triggerID=0)
Sets the maximum torque
(torque limit)
float getMaxTorque( void ) Reads the maximum torque
(torque limit)
uint8_t setKT( float gain ) Adjusts the torque constant
(KT[Nm/A])
float getKT( void ) Reads the torque constant
(KT[Nm/A])
Current control
uint8_t setTargetCurrent(float current,
int triggerID=0) Sets the target current
float getTargetCurrent(int
fromReserved=0) Reads the target current
float getPresentCurrent(int
fromCaptured=0) Reads the present current
uint8_t setMaxCurrent(float current, int
triggerID=0)
Sets the maximum current
(current limit)
uint8_t setMaxCurrent( void ) Reads the maximum
current (current limit)
uint8_t
setCurrentToVoltageGainP( float gain )
Adjusts the proportional
gain for current control
float getCurrentToVoltageGainP( void ) Reads the proportional gain
for current control
36 / 119
uint8_t
setCurrentToVoltageGainI( float gain )
Adjusts the integral gain for
current control
float getCurrentToVoltageGainI( void ) Reads the integral gain for
current control
uint8_t
setCurrentToVoltageGainD( float gain )
Adjusts the derivative gain
for current control
float getCurrentToVoltageGainD( void ) Reads the derivative gain
for current control
uint8_t setInductance(float inductance) Sets the motor inductance
float getInductance( void ) Reads the motor
inductance
uint8_t setResistance(float resistance) Sets the motor DC
resistance
float getResistance( void ) Reads the motor DC
resistance
Voltage control
uint8_t setTargetVoltage(float voltage,
int triggerID=0) Sets the target voltage
float getTargetVoltage(int
fromReserved=0) Reads the target voltage
float getPresentVoltage(int
fromCaptured=0)
Reads the present effective
voltage
uint8_t setMaxVoltage(float voltage, int
triggerID=0)
Sets the maximum effective
voltage (effective voltage
limit)
float getMaxVoltage( void )
Reads the maximum
effective voltage (effective
voltage limit)
uint8_t setKV(float KV)
Sets the back-emf
coefficient (KV value:
[rpm/V])
float getKV( void )
Reads the back-emf
coefficient (KV value:
[rpm/V])
float getSupplyVoltage( void ) Reads the supply voltage
(bus-line voltage)
37 / 119
PWM control
uint8_t setTargetDuty(float duty, int
triggerID=0) Sets the target duty ratio
float getTargetDuty(int
fromReserved=0) Reads the target duty ratio
float getPresentDuty(int
fromCaptured=0)
Reads the present duty
ratio
uint8_t setMaxDuty(float duty, int
triggerID=0)
Sets the maximum duty
ratio (duty ratio limit)
float getMaxDuty( void ) Reads the maximum duty
ratio (duty ratio limit)
Trigger
uint8_t enableTrigger( void ) Enables triggers
uint8_t disableTrigger( void ) Disables triggers (Ignores
all trigger)
uint8_t capturePresentValues(int
triggerID)
Schedules a collective
capture of variables.
Captured values are
transferred to registers
when a trigger is detected.
Collective read
and write
uint8_t setMaxValues(float angleMax,
float angleMin, float speed, float
torque, float current, float voltage, float
duty, int triggerID=0)
Collectively sets maximum
values
float getPresetValues(float *data, int
fromCaptured=0)
Collectively reads present
values
Rotational
direction setting
uint8_t
setPositiveAngleDirection(boolean
direction)
Sets the positive rotational
direction
getPositiveAngleDirection( void ) Reads the positive
rotational direction
Enable/disable uint8_t enableFeedbackcontrol( void ) Enables feedback control
uint8_t disableFeedbackcontrol( void ) Disables feedback control
Temperature
uint8_t setTemperatureLimit(int8 temp) Sets the temperature limit
float getTemperatureLimit( void ) Reads the temperature limit
float getPresentTemperature( void ) Reads the temperature
(present value)
38 / 119
Module
information
float getAbsMaxRatedAngle( void ) Reads the absolute
maximum rated angle
float getAbsMinRatedAngle( void ) Reads the absolute
minimum rated angle
float getAngleResolution( void ) Reads the resolution for
angle control
float
getAbsMaxRatedRotationSpeed( void )
Reads the absolute
maximum rated speed
float getAbsMaxRatedCurrent( void ) Reads the absolute
maximum rated current
float getAbsMaxRatedVoltage( void ) Reads the absolute
maximum rated voltage
Methods
Angle control
In angle control, the motor angle can be set to an arbitrary value. For angle control, use the
setTargetAngle command or the addTargetAngle command to set the target angle for the
motor. The motor module automatically calculates the target angle, the target speed, the
target torque, the target current, the target voltage, and the duty ratio in this order according
to the difference between target values and present values, as shown in Figure 3-4. For
example, if the target angle is set, the target speed is automatically calculated according to
the difference between the target angle and the present angle, as shown with a dotted line
in the upper part of Figure 3-5. Within the module, target values are automatically calculated
in the following order: target angle, target speed, target torque, target current, target voltage,
and duty ratio.
You can also limit the maximum of each target value to control operation. For example, in
order to rotate the motor 3600 degrees (10 turns) at 60 rpm or less, use the setMaxSpeed(60)
command to limit the maximum of the rotational speed to 60 rpm, and then use
setTargetAngle(3600) command to perform a 3600-dgree (10-turn) rotation. In this case, the
target rotational speed automatically calculated from the difference between the target angle
and the present angle will become more than 60 rpm, but rotation will be performed at 60
rpm for a while because the maximum speed is limited to 60 rpm, as shown with a solid line
in the lower part of Figure 3-5. Then, when the target rotational speed automatically
calculated from the difference between the target angle and the present angle becomes less
39 / 119
than 60 rpm, the motor is controlled so that it rotates at that rotational speed. Immediately
after a target value is set by using a setTarget command, the motor starts rotating; therefore,
a setMax command to limit a maximum value must be executed before a setTarget command
to set a target value. By using setMax commands, you can limit multiple target values. For
example, it is possible to limit both the maximum speed and the maximum torque.
Figure 3-4 Calculation of Target Values for Angle Control
40 / 119
Figure 3-5 Timing Chart of Angle Control
Figure 3-6 shows the error between the target angle and the present angle, and the offset
for the target speed. The acceptable range of the stop position of the motor is specified using
the deadband value. If the present value is within the range selected as the deadband for the
target position, then it is determined that the target position has been reached, and the motor
is stopped. The offset for the target speed to be used when the present value is outside the
deadband is specified using the punch value. Optimizing this value allows improvement of
convergence of control.
41 / 119
Figure 3-6 The Error between the Target and Present Angles and the Offset for the
Target Speed
Figure 3-7 and Figure 3-8 show transfer functions for angle control and commands
effective in angle control.
42 / 119
Figure 3-7 Transfer Functions for Angle Control and Effective set Commands
43 / 119
Figure 3-8 Transfer Functions for Angle Control and Effective get Commands
44 / 119
setTargetAngle
uint8_t setTargetAngle( float angle, int triggerID=0 )
Sets the absolute target angle assuming that the angle given at the time of start-up is zero.
Parameters
angle : Absolute target angle [degree]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
addTargetAngle
uint8_t addTargetAngle( float angle, int triggerID=0 )
Sets the target angle relative to the present angle.
Parameters
angle : Relative target angle [degree]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getTargetAngle
float getTargetAngle( boolean fromReserved=0 )
Reads the target angle.
Parameters
45 / 119
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved))
If this parameter is 0, the target value (Target Value) is read. If 1,
the reserved register (Target Value (Reserved)) is read. If omitted,
0 is assigned.
Returns
Target angle [degree]
getPresentAngle
float getPresentAngle( boolean fromCaptured=0 )
Reads the present angle.
Parameters
fromCaptured : Flag for reading from the register (Captured Value)
If this parameter is 0, the present value (Present Value) is read.
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
Present angle [degree]
resetAngle
uint8_t resetAngle( float angle=0 )
Initializes the present angle to the angle specified by the parameter ‘angle’. The new target
value is set by adding the angle specified by the parameter ‘angle’ to the difference between
the present target angle and the present angle. For example, when resetAngle(0) is executed
with both the present and target angles at 45 degrees, they both become 0 degrees. When
resetAngle(0) is executed with the present and target angles at 45 and 90 degrees,
respectively, they become 0 and 45 degrees, respectively.
Parameters
angle : The angle value for initialization. If this parameter is omitted, an
angle of 0 degrees is assigned.
Returns
0: Execution succeeded 1: Execution failed
46 / 119
setMaxAngle
uint8_t setMaxAngle( float angle, int triggerID=0 )
Sets the maximum angle in the rotational range.
Parameters
angle : Maximum angle [degree]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxAngle
float getMaxAngle( void )
Reads the maximum angle.
Returns
Maximum angle [degree]
setMinAngle
uint8_t setMinAngle( float angle, int triggerID=0 )
Sets the minimum angle in the rotational range.
Parameters
angle : Minimum angle [degree]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
47 / 119
Returns
0: Execution succeeded 1: Execution failed
getMinAngle
float getMinAngle( void )
Reads the minimum angle.
Returns
Minimum angle [degree]
setAngleToSpeedGainP
uint8_t setAngleToSpeedGainP( float gain )
Adjusts the proportional gain from the angle error to the target rotational speed. (Refer to
Figure 3-7)
Parameters
gain : Proportional gain from the angle error to the target rotational
speed [non-dimensional]
Returns
0: Execution succeeded 1: Execution failed
getAngleToSpeedGainP
float getAngleToSpeedGainP( void )
Reads the proportional gain from the angle error to the target rotational speed. (Refer to
Figure 3-7)
Returns
Proportional gain from the angle error to the target rotational speed [non-
dimensional]
setAngleToSpeedGainI
uint8_t setAngleToSpeedGainI( float gain )
Adjusts the integral gain from the angle error to the target rotational speed. (Refer to Figure
3-7)
48 / 119
Parameters
gain : Integral gain from the angle error to the target rotational speed
[non-dimensional]
Returns
0: Execution succeeded 1: Execution failed
getAngleToSpeedGainI
float getAngleToSpeedGainI( void )
Reads the integral gain from the angle error to the target rotational speed. (Refer to Figure
3-7)
Returns
Integral gain from the angle error to the target rotational speed [non-dimensional]
setAngleToSpeedGainD
uint8_t setAngleToSpeedGainD( float gain )
Adjusts the derivative gain from the angle error to the target rotational speed. (Refer to Figure
3-7)
Parameters
gain : Derivative gain from the angle error to the target rotational speed
[non-dimensional]
Returns
0: Execution succeeded 1: Execution failed
getAngleToSpeedGainD
float getAngleToSpeedGainD( void )
Reads the derivative gain from the angle error to the target rotational speed. (Refer to Figure
3-7)
Returns
Derivative gain from the angle error to the target rotational speed [non-dimensional]
49 / 119
setAngleDeadband
uint8_t setAngleDeadband(float angle)
Adjusts the deadband (compliance margin) angle for angle control. (Refer to Figure 3-6)
Parameters
angle : Deadband angle [degree]
Returns
0: Execution succeeded 1: Execution failed
getAngleDeadband
float getAngleDeadband( void )
Reads the deadband (compliance margin) angle for angle control. (Refer to Figure 3-6)
Returns
Deadband angle [degree]
setAnglePunch
uint8_t setAnglePunch(float angle)
Adjusts the punch for angle control. (Refer to Figure 3-6)
Parameters
angle : Punch [rpm]
Returns
0: Execution succeeded 1: Execution failed
getAnglePunch
float getAnglePunch( void )
Adjusts the punch for angle control. (Refer to Figure 3-6)
Returns
Punch [rpm]
Sample Code
50 / 119
Angle control sample program
This sample program newly sets control parameters to perform angle control with multiple
limitations on angle, speed, etc.
AngleControl.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1, 32 ); //Assigns a motor module
motor.resetAngle( 0.0 ); //Rests present angle to 0 degree
motor.setAngleToSpeedGainD( 0.0 ); //Sets Control Constant
motor.setSpeedToTorqueGainD( 0.0 ); //Changes from PID control to PI control
motor.setCurrentToVoltageGainD( 0.0 );
motor.setAngleDeadband( 10.0 ); //Sets deadband angle to 10.0 degree
motor.setMaxSpeed( 600.0 );
motor.setMaxCurrent( 3.0 );
motor.setMaxVoltage( 10.0 );
motor.setTargetAngle( 3600.0 ); //Sets target angle to 3600 degree
delay(5000);
}
void loop(){
motor.addTargetAngle( 720.0 ); //Adds 720 degree to target angle
51 / 119
float angle = motor.getPresentAngle(); //Obtains present angle [degree]
delay(2000);
}
52 / 119
Speed control
In speed control, the motor can be rotated at an arbitrary speed. For speed control, use the
setTargetSpeed command to set the target speed. When the motor module accepts the
setting, the target values other than the target speed are ignored, and are automatically
calculated in the following order as shown in Figure 3-9: target speed, target torque, target
current, target voltage, and duty ratio.
Like in angle control, you can limit the maximum of each target value to control operation.
For example, in order to rotate the motor gradually increasing the rotational speed up to 60
rpm at an acceleration of 10 rpm/s or less, you can use setMaxAcceleration(10) command
to limit the rotational acceleration to 10 rpm/s, and then use setTargetSpeed(60) command
to rotate it at a constant speed of 60 rpm.
Figure 3-9 Calculation of the Target Value in Speed Control
Figure 3-10 and Figure 3-11 show transfer functions for speed control and commands
effective in angle control. If the speed target has been set by the setTargetSpeed
command, then the target and maximum angles, and parameters such as gain are ignored.
53 / 119
Figure 3-10 Transfer Functions for Speed Control and Effective set Commands
54 / 119
Figure 3-11 Transfer Functions for Speed Control and Effective get Commands
55 / 119
setTargetSpeed
uint8_t setTargetSpeed( float speedRPM , int triggerID=0 )
Sets the target speed.
Parameters
speedRPM : Target speed [rpm]
triggerID : Triger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getTargetSpeed
float getTargetSpeed( boolean fromReserved=0 )
Reads the target speed.
Parameters
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved))
If this parameter is 0, the target value (Target Value) is read. If 1,
the reserved register (Target Value (Reserved)) is read. If omitted,
0 is assigned.
Returns
Target speed [rpm]
getPresentSpeed
float getPresentSpeed( boolean fromCapture=0 )
Reads the present speed.
Parameters
fromCapture : Flag for reading from the register (Captured Value)
56 / 119
If this parameter is 0, the present value (Present Value) is read.
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
Present speed [rpm]
setMaxSpeed
uint8_t setMaxSpeed( float speedRPM, int triggerID=0 )
Sets the absolute value of the maximum speed (speed limit).
Parameters
speedRPM : Maximum speed [rpm]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxSpeed
float getMaxSpeed( void )
Reads the absolute value of the maximum speed (speed limit).
Returns
Maximum speed [rpm]
setMaxAcceleration
uint8_t setMaxAcceleration( float AccelerationRPM/s, int triggerID=0 )
Sets the absolute value of the maximum acceleration (acceleration limit).
Parameters
AccelerationRPM/s : Maximum acceleration [rpm/s]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
57 / 119
otherwise, it waits until a trigger command is issued. It is
executed when the same trigger ID is issued with a trigger
command. If this parameter is omitted, the trigger ID becomes
0.
Returns
0: Execution succeeded 1: Execution failed
getMaxAcceleration
float getMaxAcceleration( void )
Reads the absolute value of the maximum acceleration (acceleration limit).
Returns
maximum acceleration [rpm/s]
setSpeedToTorqueGainP
uint8_t setSpeedToTorqueGainP( float gain )
Adjusts the proportional gain from the speed error to the target torque. (Refer to Figure 3-13)
Parameters
gain : Proportional gain from the speed error to the target torque [non-
dimensional]
Returns
0: Execution succeeded 1: Execution failed
getSpeedToTorqueGainP
float getSpeedToTorqueGainP( void )
Reads the proportional gain from the speed error to the target torque. (Refer to Figure 3-13)
Returns
Proportional gain from the speed error to the target torque [non-dimensional]
setSpeedToTorqueGainI
uint8_t setSpeedToTorqueGainI( float gain )
Adjusts the integral gain from the speed error to the target torque. (Refer to Figure 3-13)
58 / 119
Parameters
gain : Integral gain from the speed error to the target torque [non-
dimensional]
Returns
0: Execution succeeded 1: Execution failed
getSpeedToTorqueGainI
float getSpeedToTorqueGainI( void )
Adjusts the integral gain from the speed error to the target torque. (Refer to Figure 3-13)
Returns
Integral gain from the speed error to the target torque [non-dimensional]
setSpeedToTorqueGainD
uint8_t setSpeedToTorqueGainD( float gain )
Adjusts the derivative gain from the speed error to the target torque. (Refer to Figure 3-13)
Parameters
gain : Derivative gain from the speed error to the target torque [non-
dimensional]
Returns
0: Execution succeeded 1: Execution failed
getSpeedToTorqueGainD
float getSpeedToTorqueGainD( void )
Read the derivative gain from the speed error to the target torque. (Refer to Figure 3-13)
Returns
Derivative gain from the speed error to the target torque [non-dimensional]
Sample Code
This sample code newly sets control parameters to perform speed control with multiple
59 / 119
limitations on speed, voltage, etc.
SpeedControl.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1, 32 ); //Assigns a motor module
motor.setSpeedToTorqueGainD( 0.0 ); //Sets Control Constant
motor.setCurrentToVoltageGainD( 0.0 ); //Changes from PID control to PI control
motor.setMaxSpeed( 600.0 ); //Sets max values
motor.setMaxCurrent( 3.0 );
motor.setMaxVoltage( 10.0 );
motor.setTargetSpeed( 60.0 ); //Sets target rotational speed to 60rpm
}
void loop(){
float speed = motor.getPresentSpeed(); //Obtains present rotational speed [rpm]
}
60 / 119
Torque control
In torque control, the motor can be rotated at an arbitrary torque. For torque control, use
the setTargetTorque command to set the target torque. When the motor module accepts the
setting, the target values other than the target torque are ignored, and are automatically
calculated in the following order as shown in Figure 3-12: target torque, target torque, target
current, target voltage, and duty ratio.
Like in angle control, you can limit the maximum of each target value to control operation.
For example, in order to rotate the motor at an effective voltage of 10 V or less and a constant
torque of 2 mNm, you can use setMaxVoltage(10) command to limit the voltage to 10 V or
less, and then use setTargetTorque(0.002) command to rotate it at a constant torque of 2
mNm.
Figure 3-12 Calculation of the Target Value in Torque Control
Figure 3-13 and Figure 3-14 show transfer functions for torque control and commands
effective in torque control. If the torque target has been set by the setTargetTorque
command, then the target or maximum angle or speed, and parameters such as gain are
ignored.
61 / 119
Figure 3-13 Transfer Functions for Torque Control and Effective set Commands
62 / 119
Figure 3-14 Transfer Functions for Torque Control and Effective get Commands
63 / 119
setTargetTorque
uint8_t setTargetTorque( float torqueNm, int triggerID=0 )
Sets the target torque.
Parameters
torqueNm : Target torque [Nm]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getTargetTorque
float getTargetTorque( boolean fromReserved=0 )
Reads the target torque.
Parameters
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved)). If this parameter is 0, the target value (Target Value)
is read. If 1, the reserved register (Target Value (Reserved)) is
read. If omitted, 0 is assigned.
Returns
target torque [Nm]
getPresentTorque
float getPresentTorque( boolean fromCapture=0 )
Reads the present torque.
Parameters
fromCapture : Flag for reading from the register (Captured Value)
If this parameter is 0, the present value (Present Value) is read.
64 / 119
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
Present torque [Nm]
setMaxTorque
uint8_t setMaxTorque( float torqueNm, int triggerID=0 )
Sets the absolute value of the maximum torque (torque limit).
Parameters
torqueNm : Maximum torque [Nm]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxTorque
float getMaxTorque( void )
Read the absolute value of the maximum torque (torque limit).
Returns
maximum torque [Nm]
setKT
uint8_t setKT (float gain)
Adjusts the torque constant (KT value) of the motor. [Nm/A]
Parameters
gain : Torque constant of the motor (KT value) [Nm/A]
Returns
0: Execution succeeded 1: Execution failed
65 / 119
getKT
float getKT(void )
Reads the torque constant (KT value) of the motor.
Returns
Torque constant of the motor (KT value) [Nm/A]
Sample Code
This sample code newly sets control parameters to perform torque control with limitations
on voltage, etc.
TorqueControl.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1, 32 ); //Assigns a motor module
motor.setCurrentToVoltageGainD( 0.0 ); //Changes from PID control to PI control
motor.setMaxCurrent( 3.0 ); //Sets max values
motor.setMaxVoltage( 10.0 );
motor.setTargetTorque( 0.002 ); //Sets target torque to 0.002 Nm
}
void loop(){
66 / 119
float torque = motor.getPresentTorque(); //Obtains present torque [Nm]
}
67 / 119
Current control
In current control, the motor can be rotated by applying an arbitrary current to it. For current
control, use the setTargetCurrent command to set the target current. When the motor module
accepts the setting, the target values other than the target current are ignored, and are
automatically calculated in the following order as shown in Figure 3-15: target current, target
voltage, and duty ratio.
Like in angle control, you can limit the maximum of each target value to control operation.
For example, in order to rotate the motor by applying a constant current of 2 A at an effective
voltage of 10 V or less, you can use setMaxVoltage(10) command to limit the voltage to 10
V or less, and then use setTargetCurrent(2) command to rotate it at a constant current of 2
A.
Figure 3-15 Calculation of the Target Value in Current Control
Figure 3-16 and Figure 3-17 show transfer functions for current control and commands
effective in current control. If the current target has been set by the setTargetCurrent
command, then neither the target or maximum angle or speed, nor parameters such as
gain are used, and they become ineffective.
68 / 119
Figure 3-16 Transfer Functions for Current Control and Effective set Commands
69 / 119
Figure 3-17 Transfer Functions for Current Control and Effective set Commands
70 / 119
setTargetCurrent
uint8_t setTargetCurrent( float current, int triggerID=0 )
Sets the target current.
Parameters
current : Target current [A]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getTargetCurrent
float getTargetCurrent( boolean fromReserved=0 )
Reads the target current.
Parameters
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved)). If this parameter is 0, the target value (Target Value)
is read. If 1, the reserved register (Target Value (Reserved)) is
read. If omitted, 0 is assigned.
Returns
Target current [A]
getPresentCurrent
float getPresentCurrent( boolean fromCapture=0 )
Reads the present current.
Parameters
fromCapture : Flag for reading from the register (Captured Value)
If this parameter is 0, the present value (Present Value) is read.
71 / 119
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
Present current [A]
setMaxCurrent
uint8_t setMaxCurrent (float current, int triggerID=0)
Sets the absolute value of the maximum current (current limit).
Parameters
current : Maximum current [A]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxCurrent
float getMaxCurrent( void )
Reads the absolute value of the maximum current (current limit).
Returns
Maximum current [A]
setCurrentToVoltageGainP
uint8_t setCurrentToVoltageGainP( float gain )
Adjusts the proportional gain from the current error to the target voltage. (Refer to Figure
3-16)
Parameters
gain : Proportional gain from the current error to the target voltage
[non-dimensional]
72 / 119
Returns
0: Execution succeeded 1: Execution failed
getCurrentToVoltageGainP
float getCurrentToVoltageGainP( void )
Reads proportional gain from the current error to the target voltage. (Refer to Figure 3-16)
Returns
Proportional gain from the current error to the target voltage [non-dimensional]
setCurrentToVoltageGainI
uint8_t setCurrentToVoltageGainI ( float gain )
Adjusts the integral gain from the current error to the target voltage. (Refer to Figure 3-16)
Parameters
gain : Integral gain from the current error to the target voltage [non-
dimensional]
Returns
0: Execution succeeded 1: Execution failed
getCurrentToVoltageGainI
float getCurrentToVoltageGainI( void )
Reads the integral gain from the current error to the target voltage. (Refer to Figure 3-16)
Returns
Integral gain from the current error to the target voltage [non-dimensional]
setCurrentToVoltageGainD
uint8_t setCurrentToVoltageGainD( float gain )
Adjusts the derivative gain from the current error to the target voltage. (Refer to Figure 3-16)
Parameters
gain : Derivative gain from the current error to the target voltage [non-
dimensional]
73 / 119
Returns
0: Execution succeeded 1: Execution failed
getCurrentToVoltageGainD
float getCurrentToVoltageGainD( void )
Reads the derivative gain from the current error to the target voltage. (Refer to Figure 3-16)
Returns
Derivative gain from the current error to the target voltage [non-dimensional]
setInductance
uint8_t setInductance( float inductance )
Sets the inductance of the motor.
Parameter
inductance : Motor inductance [H]
Returns
0: Execution succeeded 1: Execution failed
getInductance
float getInductance( void )
Reads the inductance of the motor.
Returns
Motor inductance [H]
setResistance
uint8_t setResistance(float resistance)
Sets the DC resistance of the motor.
Parameter
resistance : Motor DC resistance
Returns
0: Execution succeeded 1: Execution failed
74 / 119
getResistance
float getResistance( void )
Reads the DC resistance of the motor.
Returns
Motor DC resistance
Sample Code
This sample code newly sets control parameters to perform current control with limitations
on voltage, etc.
CurrentControl.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1, 32 ); //Assigns a motor module
motor.setCurrentToVoltageGainD( 0.0 ); //Changes from PID control to PI control
motor.setMaxVoltage( 10.0 ); //Sets max values
motor.setTargetCurrent( 1.0 ); //Sets target current to 1 A
}
void loop(){
75 / 119
float current = motor.getPresentCurrent(); //Obtains present current [A]
}
76 / 119
Voltage control
In voltage control, the motor can be rotated by applying an arbitrary voltage to it. For
voltage control, use the setTargetVoltage command to set the target voltage. When the motor
module accepts the setting, the target values other than the target voltage are ignored, and
are automatically calculated in the following order as shown in Figure 3-18: target voltage
and duty ratio.
Like in angle control, you can limit the maximum of each target value to control operation.
Figure 3-18 Calculation of the Target Value in Voltage Control
Figure 3-19 and Figure 3-20 show transfer functions executed within the motor module for
voltage control, and commands effective in voltage control. If the target voltage has been
set by the setTargetVoltage command, then the target and maximum values for angle,
speed, etc., and parameters such as gain are ignored.
77 / 119
Figure 3-19 Transfer Functions for Voltage Control and Effective set Commands
78 / 119
Figure 3-20 Transfer Functions for Voltage Control and Effective get Commands
79 / 119
setTargetVoltage
uint8_t setTargetVoltage( float voltage, int triggerID=0 )
Sets the target voltage.
Parameter
voltage : Target voltage [V]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getTargetVoltage
float getTargetVoltage(boolean fromReserved=0)
Reads the target voltage.
Parameters
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved)). If this parameter is 0, the target value (Target Value)
is read. If 1, the reserved register (Target Value (Reserved)) is
read. If omitted, 0 is assigned.
Returns
Target voltage [V]
getPresentVoltage
float getPresentVoltage( boolean fromCapture=0 )
Reads the present effective voltage.
Parameters
fromCapture : Flag for reading from the register (Captured Value)
If this parameter is 0, the present value (Present Value) is read.
80 / 119
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
Present voltage [V]
setMaxVoltage
uint8_t setMaxVoltage( float voltage, int triggerID=0 )
Sets the absolute value of the maximum effective voltage (effective voltage limit).
Parameter
voltage : Maximum voltage [V]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxVoltage
float getMaxVoltage( void )
Reads the absolute value of the maximum effective voltage (effective voltage limit).
Returns
Maximum voltage [V]
setKV
uint8_t setKV( float gain )
Adjusts the constant number of rotations (KV value) of the motor.
Parameters
gain : Constant number of rotations (KV value) of the motor [rpm/V]
Returns
0: Execution succeeded 1: Execution failed
81 / 119
getKV
float getKV( void )
Reads the constant number of rotations (KV value) of the motor.
Returns
Constant number of rotations (KV value) of the motor [rpm/V]
getSupplyVoltage
float getSupplyVoltage( void )
Reads the supply voltage (bus-line voltage) of the motor.
Returns
Supply voltage of the motor [V]
82 / 119
Sample Code
This sample code applies 10 V to the motor.
VoltageControl.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1, 32 ); //Assigns a motor module
motor.setTargetVoltage( 10.0 ); //Sets target voltage to 10 V
}
void loop(){
float voltage = motor.getPresentVoltage(); //Obtains present voltage [V]
}
83 / 119
PWM control
In PWM control, the motor can be rotated by applying a pulse with an arbitrary duty ratio to
it. For PWM control, use the setTargetDuty command to set the target duty ratio. When the
motor module accepts the setting, the target values other than the target duty ratio are
ignored, and the duty ratio is calculated as shown in Figure 3-21.
Figure 3-21 Calculation of the Target Value in PWM Control
Figure 3-22 and Figure 3-23 show transfer functions for PWM control, and commands
effective in PWM control. If the target duty ratio has been set by the setTargetDuty
command, then neither the target or maximum angle, speed, etc., nor parameters such as
gain are used, and they become ineffective.
84 / 119
Figure 3-22 Transfer Functions for PWM Control and Effective set Commands
85 / 119
Figure 3-23 Transfer Functions for PWM Control and Effective get Commands
86 / 119
setTargetDuty
uint8_t setTargetDuty( float duty, int triggerID=0 )
Sets the duty ratio (0 to 1)
Parameter
duty : Target duty ratio [non-dimensional]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getTargetVoltage
float getTargetVoltage(boolean fromReserved=0)
Reads the target voltage.
Parameters
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved)). If this parameter is 0, the target value (Target Value)
is read. If 1, the reserved register (Target Value (Reserved)) is
read. If omitted, 0 is assigned.
Returns
Target voltage [V]
getPresentDuty
float getPresentDuty( boolean fromCapture=0 )
Reads the present duty ratio.
Parameters
fromCapture : Flag for reading from the register (Captured Value)
If this parameter is 0, the present value (Present Value) is read.
87 / 119
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
Present duty ratio [non-dimensional]
setMaxDuty
uint8_t setMaxDuty( float duty, int triggerID=0 )
Sets the absolute value of the maximum duty ratio (duty ratio limit).
Parameters
duty : maximum duty ratio [non-dimensional]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxDuty
float getMaxDuty( void )
Reads the absolute value of the maximum duty ratio (duty ratio limit).
Returns
maximum duty ratio [non-dimensional]
Sample Code
This sample code applies a pulse with a duty ratio of 0.5 to the motor.
PWMControl.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
88 / 119
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 1, 32 ); //Assigns a motor module
motor.setTargetDuty( 0.5 ); //Sets target duty to 0.5
}
void loop(){
float duty = motor.getPresentDuty(); //Obtains present duty
}
89 / 119
Trigger
Trigger commands are used to operate multiple modules simultaneously or to obtain the
status of multiple modules at the same time point.
Figure 3-24 shows an operating model of the motor module. When a setTarget command is
used with no trigger ID specified, the target value (Target Value (Active)) is directly written to
and is immediately applied to control operation. Meanwhile, when a setTarget command is
used with a trigger ID specified, the reserved register (Target Value (Reserved)) is written to.
The value of the reserved register is transferred to the target value (Target Value (Active))
and is applied to control operation when the applicable trigger ID is received through a trigger
command. The target values for multiple motors can be simultaneously made effective by
using the same trigger ID for setTarget commands for these motors and issuing a trigger
command.
Figure 3-24 Operating Model of the Motor Module
Figure 3-25 shows timing charts of immediate and triggered operations of setTarget
commands. In a configuration where multiple modules are connected to the same bus, it is
impossible to simultaneously transfer a command to multiple modules. Therefore, if the
motor1.setTargetAngle(90) command and the motor2.setTargetAngle(90) command are
executed in this order, the motors start separately at the interval required to transfer the
commands, as shown in the upper part of Figure 3-25. Meanwhile, if the
90 / 119
motor1.setTargetAngle(90,1) command, the motor2.setTargetAngle(90,1) command, and the
controlGlobalTrigger(1) command are executed in this order, the settings of the motors are
enabled simultaneously when the trigger command is received, so that the two motors can
start at the same time, as shown in the lower part of Figure 3-25.
Figure 3-25 Timing Charts of Immediate and Triggered Operations of setTarget
Commands
Figure 3-26 shows timing charts of immediate and triggered operations of getPresent
commands. If the motor1.getPresentAngle() command, the motor1.getPresentSpeed()
command, the motor2.getPresentAngle() command, and the motor2.getPresentSpeed()
91 / 119
command are executed in this order, the commands obtain an angle or a speed separately
at the intervals required to transfer the commands, as shown in the upper part of Figure 3-26.
Meanwhile, if the motor1.captureValues(1) command, the motor2.captureValues(1)
command, and the controlglobalTrigger(1) command are executed in this order, the present
values (Present Value) such as a speed and an angle that are given when the trigger
command is received are transferred to the registers (Captured Value), as shown in the lower
part of the Figure 3-26. The speeds and angles given at the same time point that are stored
in the same registers (Captured Value) can be obtained by using the
motor1.getPresentAngle(1) command, the motor1.getPresentSpeed(1) command, the
motor2.getPresentAngle(1) command, and the motor2.getPresentSpeed(1) command to
read the values sequentially.
92 / 119
Figure 3-26 Timing Charts of Immediate and Triggered Operations of getPresent
Commands
Figure 3-27 shows an example of periodic control of multiple modules. In periodic control,
the following sequential operations are performed: (1) obtaining data from each module, (2)
using transfer functions to calculate the next target values based on the obtained values, (3)
assigning the next target values to the reserved registers of each module, and (4) using a
93 / 119
trigger command to make the target values effective at the same time and capturing the
present values into registers; multiple modules can be periodically controlled by executing
the trigger command in (4) synchronously with the control cycle.
Figure 3-27 Periodic Control of Multiple Modules
disableTrigger
uint8_t disableTrigger( void )
Disables the trigger function. Trigger IDs set by setTarget commands or setMax commands
are made ineffective, and all triggers are ignored.
Returns
0: Execution succeeded 1: Execution failed
enableTrigger
uint8_t enableTrigger( void )
Enables the trigger function. The trigger function is enabled after it is disabled by
disableTrigger.
Returns
94 / 119
0: Execution succeeded 1: Execution failed
capturePresentValues
uint8_t capturePresentValues( int triggerID )
Transfers present values (Present Value) to registers (Captured Value). Alternatively it sets
a trigger ID used to transfer present values (Present Value) to registers (Captured Value).
Parameter
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
Sample Code
This sample code obtains multiple present values (such as speed and angle) at the same
time point.
Capture1.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor.attach( 2, 32 ); //Assigns a motor module
motor.setTargetAngle( 90.0 ); //Sets target angle to 90 degree
95 / 119
}
void loop(){
motor.capturePresentValue();
float angle = motor.getPresentAngle(1); //Obtains present angle [degree]
float speed = motor.getPresentSpeed(1); //Obtains present rotational speed[rmp]
}
This sample code obtains the present values of multiple motors at the same time point.
Capture2.ino
#include <Control.h> //Includes Control.h
#include <Wire.h>
#include <SPI.h>
ControlRoot root; //Declares root class
ControlMotor motor1, motor2; //Declares motor module
void setup() {
root.controlInit(); //Initializes Control API
motor1.attach( 2, 32 ); //Assigns a motor modules
motor2.attach( 2, 83 );
motor1.setTargetAngle( 90.0 ); //Sets target angle to 90 degree
motor2.setTargetAngle( 90.0 );
}
void loop(){
motor1.capturePresentValues(1); // Captures present value to buffer
motor2.capturePresentValues(1);
96 / 119
root.controlGlobalTrigger(1);
float angle1 = motor1.getPresentAngle(1); // Obtains present angle [degree]
float angle2 = motor2.getPresentAngle(1);
}
97 / 119
Collective read and write
The maximum values (Max Value) and the present values (Present Value) shown in Figure
3-24 include multiple parameters, and the commands used to collectively read or write them
are described below.
setMaxValues
uint8_t setMaxValues(float angleMax, float angleMin, float speed, float torque, float current,
float voltage, float duty, int triggerID=0)
Sets maximum values collectively.
Parameter
angleMax : Maximum angle [degree]
angleMin : Minimum angle [degree]
speed : Maximum speed [rpm]
acceleration : Maximum acceleration [rpm/s]
torque : Maximum torque [Nm]
current : Maximum current [A]
voltage : Maximum voltage [V]
duty : Maximum duty ratio [non-dimensional]
triggerID : Trigger ID
If this parameter is 0, the command is immediately executed;
otherwise, it waits until a trigger command is issued. It is executed
when the same trigger ID is issued with a trigger command. If this
parameter is omitted, the trigger ID becomes 0.
Returns
0: Execution succeeded 1: Execution failed
getMaxValues
uint8_t getMaxValues(float *data, boolean fromReserved=0)
Reads maximum values collectively.
Parameter
*data : Pointer to the location where maximum values are stored
98 / 119
fromReserved : Flag for reading from the reserved register (Target Value
(Reserved)). If this parameter is 0, the target value (Target Value)
is read. If 1, the reserved register (Target Value (Reserved)) is
read. If omitted, 0 is assigned.
Returns
0: Execution succeeded 1: Execution failed
getPresetValues
uint8_t getPresetValues(float *data, boolean fromCapture=0)
Reads present values collectively.
Parameters
*data : Pointer to the location where present values are stored
fromCapture : Flag for reading from the register (Captured Value)
If this parameter is 0, the present value (Present Value) is read.
If 1, the register (Captured Value) is read. If omitted, 0 is assigned.
Returns
0: Execution succeeded 1: Execution failed
99 / 119
Rotational direction setting
setPositiveAngleDirection
uint8_t setPositiveAngleDirection(boolean direction)
Sets the rotational direction (positive).
Parameter
direction : Positive rotational direction, 0: CCW (Default), 1: CW
Returns
0: Execution succeeded 1: Execution failed
boolean getPositiveAngleDirection
uint8_t getPositiveAngleDirection( void )
Reads the rotational direction (positive).
Returns
Positive rotational direction
Whether to use feedback
The commands to enable or disable feedback select whether to enable or disable the control
of the motor. If it is disabled, the motor terminal is released. Note that feedback is enabled
after the motor module is powered on.
enableFeedbackcontrol
uint8_t enableFeedbackcontrol( void )
Enables the feedback control.
Returns
0: Execution succeeded 1: Execution failed
100 / 119
disableFeedbackcontrol
uint8_t disableFeedbackcontrol( void )
Disables the feedback control. The motor is released.
Returns
0: Execution succeeded 1: Execution failed
101 / 119
Temperature
Obtain the maximum operating temperature or present temperate of the motor.
setTemperatureLimit
uint8_t setTemperatureLimit( uint8_t temp )
Sets the upper temperature limit.
Parameter
temp : Temperature limit [degree Celsius]
Returns
0: Execution succeeded 1: Execution failed
getTemperatureLimit
uint8_t getTemperatureLimit( void )
Reads the upper temperature limit.
Returns
Temperature limit [degree Celsius]
getPresentTemperature
uint8_t getPresentTemperature( void )
Reads the temperature (present value).
Returns
Temperature [degree Celsius]
102 / 119
Module information
Obtain motor-specific values such as an absolute maximum rating.
getAbsMaxRatedAngle
float getAbsMaxRatedAngle( void )
Reads the absolute maximum rated angle.
Returns
Absolute maximum rated angle [degree]
getAbsMinRatedAngle
float getAbsMinRatedAngle( void )
Reads the absolute minimum rated angle.
Returns
Absolute minimum rated angle [degree]
getAngleResolution
float getAngleResolution( void )
Reads the angle resolution for angle control.
Returns
Angle resolution [degree]
getAbsMaxRatedRotationSpeed
float getAbsMaxRatedRotationSpeed( void )
Reads the absolute maximum rated speed.
Returns
Absolute maximum rated speed [rpm]
getAbsMaxRatedCurrent
float getAbsMaxRatedCurrent( void )
Reads the absolute maximum rated current.
103 / 119
Returns
Absolute maximum rated current [A]
getAbsMaxRatedVoltage
float getAbsMaxRatedVoltage( void )
Reads the absolute maximum rated voltage.
Returns
Absolute maximum rated voltage [V]
104 / 119
3.4.4 Serial Communication Class
The Serial Communication class consists of commands for communication with modules.
Table 3-8 List of the Methods of the Serial Communication Class
Method Name Description
uint8_t serialWrite(uint8_t busNumber, uint8_t address,
uint8_t commandCode, uint8_t, byteCount, uint8_t *data)
Serial communication write
command
uint8_t serialRead(uint8_t busNumber, uint8_t address,
uint8_t commandCode, uint8_t byteCount, uint8_t *data)
Serial communication read
command
uint8_t setTableValue(uint8_t busNumber, int index, int
byteCount, byte *data)
Incremental write to the
control table for modules
uint8_t getTableValue(uint8_t busNumber, int index, int
byteCount, byte *data)
Incremental read from the
control table for modules
Methods
serialWrite
uint8_t serialWrite(uint8_t busNumber,uint8_t address, uint8_t commandCode, uint8_t,
byteCount, uint8_t *data )
Serial communication write command.
Parameters
busNumber : Bus number (Refer to Table 3-5)
address : Module I2C address
commandCode : Command code
byteCount : Byte count
*data : Pointer to the data to be written
Returns
0: Execution succeeded 1: Execution failed
serialRead
uint8_t serialRead(uint8_t busNumber,uint8_t address, uint8_t commandCode, uint8_t
byteCount, uint8_t *data )
105 / 119
Serial communication read command.
Parameters
busNumber : Bus number(Refer to Table 3-5)
address : Module I2C address
commandCode : Command code
byteCount : Byte count
*data : Pointer to the data to be read
Returns
0: Execution succeeded 1: Execution failed
setTableValue
uint8_t setTableValues(uint8_t busNumber, uint8_t index, uint8_t byteCount, byte *data)
Incremental write to the control table for modules.
Parameters
busNumber : Bus number(Refer to Table 3-5)
address : Module I2C address
index : Index on the module control table
byteCount : Byte count
*data : Pointer to the data to be written
Returns
0: Execution succeeded 1: Execution failed
getTableValues
uint8_t getTableValue(uint8_t busNumber, uint8_t index, uint8_t byteCount, byte *data)
Incremental read from the control table for modules.
Parameters
busNumber : Bus number(Refer to Table 3-5)
address : Module I2C address
index : Index on the module control table
byteCount : Byte count
*data : Pointer to the data to be written
106 / 119
Returns
0: Execution succeeded 1: Execution failed
107 / 119
4 Serial Communication Specifications
4.1 Overview
This section describes the I2C serial communication standards and the packet specifications
that are used for communication with modules supporting the Control API.
Figure 4-1 Serial communication standards for data transfer
4.2 Applicable Communication Standards
The I2C Standard is used for I2C serial communication.
I2C Standard :http://www.nxp.com/
The physical and data link layers are compliant with the I2C Standard. Address Resolution
Protocol, CRC (Cyclic Redundancy Check) and retransmission control are scheduled to be
implemented in order to deal with communication errors in the future.
108 / 119
4.3 Packet Specifications
Figure 4-2 shows the packet structure. In the future, the protocol will be changed to one with
CRC. As for command codes, the next section provides details.
Figure 4-2 Packet Specifications
109 / 119
4.4 Command Codes
The Arduino and the motor module use serial communication to transmit and receive
desired control parameters. The command codes indicate which control parameter will be
transmitted and received. Table 4-1 lists the command codes.
Command Code : Indicates the command code.
Control parameter to be accessed: Indicates the motor control parameter to be accessed.
Byte Count : Indicates the byte count.
Data Bytes(Type) : Indicates the content of the data bytes. ‘()’ indicates the type of
the data. ‘uint8_t’ is one byte, and ‘float’ is four bytes. The byte
order is little-endian. When multiple parameters are to be
transmitted and received, descriptions are provided in the order
of data bytes.
Table 4-1 List of the Command Codes
Command
Code Control Parameter To Be Accessed
Byte
Count Data Bytes(type)
0x00 Target Values
(Active)
Parameter Code 1 Parameter Code(uint8_t)
0x01 Parameter 4 Parameter(float)
0x02 Target Values
(Reserved)
Parameter Code 1 Parameter Code(uint8_t)
0x03 Parameter 4 Parameter(float)
0x04 Trigger ID 1 Trigger ID(uint8_t)
0x05
Max Values
(Active)
MaxAngle 4 Angle(float)
0x06 MinAngle 4 Angle(float)
0x07 AbsMaxSpeed 4 Speed(float)
0x08 AbsMaxAcceleration 4 Accel(float)
0x09 AbsMaxTorque 4 Torque(float)
0x0A AbsMaxCurrent 4 Current(float)
0x0B AbsMaxVoltage 4 Volt(float)
0x0C AbsMaxDuty 4 Duty(float)
0x0D
Max Values
(Reserved)
MaxAngle 5 Angle(float)
0x0E MinAngle 5 Angle(float)
0x0F AbsMaxSpeed 5 Speed(float)
0x10 AbsMaxAcceleration 4 Accel(float)
110 / 119
0x11 AbsMaxTorque 5 Torque(float)
0x12 AbsMaxCurrent 5 Current(float)
0x13 AbsMaxVoltage 5 Volt(float)
0x14 AbsMaxDuty 5 Duty(float)
0x15 Trigger ID 1 Trigger ID(uint8_t)
0x16
Present
Values
(Active)
Angle 4 Angle(float)
0x17 Speed 4 Speed(float)
0x18 Acceleration 4 Accel(float)
0x19 Torque 4 Torque(float)
0x1A Current 4 Current(float)
0x1B Voltage 4 Volt(float)
0x1C Duty 4 Duty(float)
0x1D
Captured
Values
Angle 4 Angle(float)
0x1E Speed 4 Speed(float)
0x1F Acceleration 4 Accel(float)
0x20 Torque 4 Torque(float)
0x21 Current 4 Current(float)
0x22 Voltage 4 Volt(float)
0x23 Duty 4 Duty(float)
0x24 Trigger ID 1 Trigger ID(uint8_t)
0x25 Temperature 4 Temp(float)
0x26 Supply Voltage 4 Volt(float)
0x27 Reset Angle 1 data(uint8_t)
0x28 Trigger 1 data(uint8_t)
0x29 Factory Reset 1 data(uint8_t)
0x2A Reboot 1 data(uint8_t)
0x2B Status 1 data(uint8_t)
0x2C Error Code 1 data(uint8_t)
0x2D Feedback 1 data(uint8_t)
0x2E LED 2 data(uint8_t)
0x2F Angle to
Speed
Gain
P 4 Param(float)
0x30 I 4 Param(float)
0x31 D 4 Param(float)
0x32 P 4 Param(float)
0x33 I 4 Param(float)
111 / 119
0x34
Speed to
Torque
Gain
D 4 Param(float)
0x35 KT 4 Param(float)
0x36 Motor Inductance 4 Param(float)
0x37 Motor Resistance 4 Param(float)
0x38 Current to
Voltage
Gain
P 4 Param(float)
0x39 I 4 Param(float)
0x3A D 4 Param(float)
0x3B KV 4 Param(float)
0x3C Deadband 4 Param(float)
0x3D Punch 4 Param(float)
0x3E
Absolute
Maximum
MaxAngle 4 Angle(float)
0x3F MinAngle 4 Angle(float)
0x40 AbsMaxSpeed 4 Speed(float)
0x41 AbsMaxAcceleration 4 Accel(float)
0x42 AbsMaxTorque 4 Torque(float)
0x43 AbsMaxCurrent 4 Current(float)
0x44 AbsMaxVoltage 4 Volt(float)
0x45 MaxTemperature 4 Temp(float)
0x46 MinTemperature 4 Temp(float)
0x47 Angle Resolution 4 Angle(float)
0x48 Positive Angle Direction 1 data(uint8_t)
0x48 to
0x79
0x7A
Batch
Access
Target Values
(Active) 6
Parameter Code(uint8_t),
Parameter(float)
0x7B Target Values
(Reserved)
7
Parameter Code(uint8_t),
Parameter(float),
Trigger ID(uint8_t)
0x7C Max Values
(Active) 28
MaxAngle to
AbsMaxDuty(float)
0x7D Max Values
(Reserved)
29
MaxAngle to
AbsMaxDuty(float),
TriggerID(uint8_t)
112 / 119
0x7E Present Values
(Active) 28 Angle to Duty(float)
0x7F Captured Values 28 Angle to Duty(float)
0x80 Table Direct
Access
Pointer 1 data(uint8_t)
0x81 Data N
Command codes can either separately or collectively access the parameters used for
transfer functions for motor control. Figure 4-3 shows the relationship between the command
codes and the control parameters to be accessed. In order to access maximum values (Max
Values) or present values (Present Values), use the command codes corresponding to their
respective parameters. For example, the command codes for the maximum angle and the
present angle are “0x05” and “0x16”, respectively; in order to collectively read from or write
to multiple parameters for maximum values (Max Values (Active)), “0x7E” must be used as
the command code. To access present values (Target Values), use two types of command
codes. The first command code specifies the type of the target parameter (0: angle, 1: speed,
2: torque, 3: current, 4: voltage, 5: duty, etc.), and the other one specifies the target value
itself. For example, in order to perform speed control at 60 rpm, use the command code
“0x00” to specify the type of the target parameter and then use the command code “0x01” to
specify the target value. The motor module inputs the target value through only one transfer
function according to the type of the target parameter.
Some command codes access a parameter by specifying the address on the control table,
like a conventional command servo. Specifically, you can use the command code “0x80” to
specify the location to be accessed on the module control table and then use the command
code “0x81” to transfer the desired size of data. The access positon is automatically
incremented to sequentially store the data in the control table.
Command codes are common to motors that support the Control API. This makes it possible
to use the same command codes even for different types or models of motors, eliminating
the need for changes to programs. Also, this makes it easier to substitute a motor with a
different maximum output or of a different type according to the circumstances.
113 / 119
Figure 4-3 Command Codes and Accessed Control Parameters
114 / 119
5 Modules
Various modules, such as motor modules, sensor modules, and battery modules, are
planned to be provided.
5.1 Motor Modules
There are various types of motor modules such as a DC motor module and an AC motor
module.
5.1.1 DC Motor Module
Control Table
The motor module refers to values on the control table to control a motor. They can be
rewritten through serial communication with the control table. Figure 5-1 shows the control
table.
RAM/FLASH: Values in RAM are returned to the initial values each time the power is
turned on. Those in FLASH are retained even after the power is turned on.
Index: Indicates the parameter position. To directly access the control table, use
Index values.
Initial value: Values to which parameters are set by power-up or factory reset.
Figure 5-1 Control Table
RAM/
FLASH INDEX
Content
Type
(byte) Initial Value
RAM
0 Target
Value
(Active)
Parameter Type uint8_t (1) 0
1 Parameter float (4) 0
2 Target
Value
(Reserved)
Parameter Type uint8_t (1) 0
3 Parameter float (4) 0
4 Trigger ID uint8_t (1) 0
5 Max Value
(Active)
MaxAngle float (4) ∞
6 MinAngle float (4) -∞
115 / 119
7 AbsMaxSpeed float (4) 8700
8 AbsMaxAcceleration float (4) ∞
9 AbsMaxTorque float (4) 0.6504
10 AbsMaxCurrent float (4) 2.35
11 AbsMaxVoltage float (4) 30
12 AbsMaxDuty float (4) 125
13
Max Value
(Reserved)
MaxAngle float (4) ∞
14 MinAngle float (4) -l
15 AbsMaxSpeed float (4) 8700
16 AbsMaxAcceleration float (4) ∞
17 AbsMaxTorque float (4) 0.6504
18 AbsMaxCurrent float (4) 2.35
19 AbsMaxVoltage float (4) 30
20 AbsMaxDuty float (4) 125
21 Trigger ID uint8_t (1) ∞
22
Present
Values
(Active)
Angle float (4) 0
23 Speed float (4) 0
24 Acceleration float (4) 0
25 Torque float (4) 0
26 Current float (4) 0
27 Voltage float (4) 0
28 Duty float (4) 0
29
Capture
Values
Angle float (4) 0
30 Speed float (4) 0
31 Acceleration float (4) 0
32 Torque float (4) 0
33 Current float (4) 0
34 Voltage float (4) 0
35 Duty float (4) 0
36 Trigger ID uint8_t (1) 0
37 Temperature float (4) 0
38 Supply Voltage float (4) 0
39 Reset Angle float (4) 0
40 Trigger uint8_t (1) 0
41 Factory Reset uint8_t (1) 0
116 / 119
42 Reboot uint8_t (1) 0
43 Status uint8_t (1) 0
44 Error Code uint8_t (1) 0
45 Feedback uint8_t (1) 0
46 LED uint8_t (1) 0
FLASH
47 Angle to
Speed
Gain
P float (4) 15
48 I float (4) 0
49 D float (4) 0
50 Speed to
Torque
Gain
P float (4) 0.06
51 I float (4) 0.025
52 D float (4) 0
53 KT float (4) 0.02479
54 Motor Inductance float (4) 0
55 Motor Resistance float (4) 0
56 Current to
Voltage
Gain
P float (4) 5
57 I float (4) 500
58 D float (4) 0
59 KV float (4) 0.02479
60 Deadband float (4) 5
61 Punch float (4) 0
62
Absolute
Maximum
MaxAngle float (4) ∞
63 MinAngle float (4) -∞
64 AbsMaxSpeed float (4) 8700
65 AbsMaxAcceleration float (4) ∞
66 AbsMaxTorque float (4) 0.6504
67 AbsMaxCurrent float (4) 2.35
68 AbsMaxVoltage float (4) 30
69 MaxTemperature float (4) 125
70 MinTemperature float (4) -40
71 Angle Resolution float (4) 5
72 Positive Angle Direction uint8_t (1) 0
73 Encoder Slit Count uint8_t (1) 100
117 / 119
Control Line Diagram
Figure 5-2 shows a control line diagram.
Figure 5-2 Control Line Diagram
118 / 119