PSL_2021 / servomotor_MX12_Lorenzo

Dependents:   PSL_ROBOT_lorenzo robot_lorenzo recepteur_mbed_os_6

Committer:
denis2nis
Date:
Sat Nov 06 08:29:28 2021 +0000
Revision:
8:e74ef93ae660
Parent:
7:68983a9b0531
Child:
9:b4a5187fdec6
Arrange and comment (cont.)

Who changed what in which revision?

UserRevisionLine numberNew contents of line
denis2nis 1:a9ba9cf928fe 1 /**
denis2nis 8:e74ef93ae660 2 * @file MX12.h
denis2nis 8:e74ef93ae660 3 * @brief this header file will contain all required definitions and
denis2nis 8:e74ef93ae660 4 * basic utilities functions to manage au bus of servomotor
denis2nis 8:e74ef93ae660 5 * Dynaminel MX12
denis2nis 8:e74ef93ae660 6 *
denis2nis 8:e74ef93ae660 7 */
denis2nis 8:e74ef93ae660 8 #ifndef MBED_MX12_H_
denis2nis 8:e74ef93ae660 9 #define MBED_MX12_H_
denis2nis 0:7556356a8bcd 10
denis2nis 0:7556356a8bcd 11 #include "mbed.h"
denis2nis 0:7556356a8bcd 12
denis2nis 5:0cf54586a4be 13 #define MX12_DATA_MAX_SIZE 256
denis2nis 5:0cf54586a4be 14 #define MX12_MAX_MOTOR_COUNT 16
denis2nis 5:0cf54586a4be 15
denis2nis 2:02f3323a107d 16 /* Dynamixel protocol v1.0 : Instructions
denis2nis 2:02f3323a107d 17 ******************************************/
denis2nis 2:02f3323a107d 18 #define PROTOCOL_INSTRUCTION_PING 0x01
denis2nis 2:02f3323a107d 19 #define PROTOCOL_INSTRUCTION_READ 0x02
denis2nis 2:02f3323a107d 20 #define PROTOCOL_INSTRUCTION_WRITE 0x03
denis2nis 2:02f3323a107d 21 #define PROTOCOL_INSTRUCTION_REG_WRITE 0x04
denis2nis 2:02f3323a107d 22 #define PROTOCOL_INSTRUCTION_ACTION 0x05
denis2nis 2:02f3323a107d 23 #define PROTOCOL_INSTRUCTION_FACTORY_RESET 0x06
denis2nis 2:02f3323a107d 24 #define PROTOCOL_INSTRUCTION_REBOOT 0x08
denis2nis 2:02f3323a107d 25 #define PROTOCOL_INSTRUCTION_SYNC_WRITE 0x83
denis2nis 2:02f3323a107d 26 #define PROTOCOL_INSTRUCTION_BULK_READ 0x92
denis2nis 2:02f3323a107d 27
denis2nis 5:0cf54586a4be 28 /* Dynamixel protocol v1.0 : Contro table content
denis2nis 5:0cf54586a4be 29 ************************************************/
denis2nis 5:0cf54586a4be 30 #define CONTROL_TABLE_MODEL_NUMBER 0
denis2nis 5:0cf54586a4be 31 #define CONTROL_TABLE_FIRMWARE_VERSION 2
denis2nis 5:0cf54586a4be 32 #define CONTROL_TABLE_ID 3
denis2nis 5:0cf54586a4be 33 #define CONTROL_TABLE_BAUD_RATE 4
denis2nis 5:0cf54586a4be 34 #define CONTROL_TABLE_RETURN_DELAY_TIME 5
denis2nis 5:0cf54586a4be 35 #define CONTROL_TABLE_CW_ANGLE_LIMIT 6
denis2nis 5:0cf54586a4be 36 #define CONTROL_TABLE_CCW_ANGLE_LIMIT 8
denis2nis 5:0cf54586a4be 37 #define CONTROL_TABLE_TEMPERATURE_LIMIT 11
denis2nis 5:0cf54586a4be 38 #define CONTROL_TABLE_MIN_VOLTAGE_LIMIT 12
denis2nis 5:0cf54586a4be 39 #define CONTROL_TABLE_MAX_VOLTAGE_LIMIT 13
denis2nis 5:0cf54586a4be 40 #define CONTROL_TABLE_MAX_TORQUE 14
denis2nis 5:0cf54586a4be 41 #define CONTROL_TABLE_STATUS_RETURN_LEVEL 16
denis2nis 5:0cf54586a4be 42 #define CONTROL_TABLE_ALARM_LED 17
denis2nis 5:0cf54586a4be 43 #define CONTROL_TABLE_SHUTDOWN 18
denis2nis 5:0cf54586a4be 44 #define CONTROL_TABLE_MULTITURN_OFFSET 20
denis2nis 5:0cf54586a4be 45 #define CONTROL_TABLE_RESOLUTION_DIVIDER 22
denis2nis 5:0cf54586a4be 46 #define CONTROL_TABLE_TORQUE_ENABLE 24
denis2nis 5:0cf54586a4be 47 #define CONTROL_TABLE_LED 25
denis2nis 5:0cf54586a4be 48 #define CONTROL_TABLE_P_GAIN 26
denis2nis 5:0cf54586a4be 49 #define CONTROL_TABLE_I_GAIN 27
denis2nis 5:0cf54586a4be 50 #define CONTROL_TABLE_D_GAIN 28
denis2nis 5:0cf54586a4be 51 #define CONTROL_TABLE_GOAL_POSITION 30
denis2nis 5:0cf54586a4be 52 #define CONTROL_TABLE_MOVING_SPEED 32
denis2nis 5:0cf54586a4be 53 #define CONTROL_TABLE_TORQUE_LIMIT 34
denis2nis 5:0cf54586a4be 54 #define CONTROL_TABLE_PRESENT_POSITION 36
denis2nis 5:0cf54586a4be 55 #define CONTROL_TABLE_PRESENT_SPEED 38
denis2nis 5:0cf54586a4be 56 #define CONTROL_TABLE_PRESENT_LOAD 40
denis2nis 5:0cf54586a4be 57 #define CONTROL_TABLE_PRESENT_VOLTAGE 42
denis2nis 5:0cf54586a4be 58 #define CONTROL_TABLE_PRESENT_TEMPERATURE 43
denis2nis 5:0cf54586a4be 59 #define CONTROL_TABLE_REGISTRED_INSTRUCTION 44
denis2nis 5:0cf54586a4be 60 #define CONTROL_TABLE_MOVING 46
denis2nis 5:0cf54586a4be 61 #define CONTROL_TABLE_LOCK 47
denis2nis 5:0cf54586a4be 62 #define CONTROL_TABLE_PUNCH 48
denis2nis 5:0cf54586a4be 63 #define CONTROL_TABLE_GOAL_ACCELERATION 73
denis2nis 2:02f3323a107d 64
denis2nis 2:02f3323a107d 65 /**
denis2nis 8:e74ef93ae660 66 * @brief Class to communicate with Dynamixel MX12 servomotors
denis2nis 1:a9ba9cf928fe 67 *
denis2nis 2:02f3323a107d 68 * @details
denis2nis 8:e74ef93ae660 69 *
denis2nis 2:02f3323a107d 70 * The servomotors are daisy chained to a serial link of the target
denis2nis 2:02f3323a107d 71 * microcontroller. The class ensures the initialization of serial link
denis2nis 8:e74ef93ae660 72 * and the management of communications mainly to control rotational
denis2nis 8:e74ef93ae660 73 * speed of servomotors.
denis2nis 8:e74ef93ae660 74 *
denis2nis 2:02f3323a107d 75 * Transmission of messages to the servomotors is blocking while
denis2nis 2:02f3323a107d 76 * reception is non-blocking thanks to the use of an interrupt routine.
denis2nis 5:0cf54586a4be 77 *
denis2nis 5:0cf54586a4be 78 * @author Titouan Soulard (creator and maintainer until April 2021)
denis2nis 5:0cf54586a4be 79 * @author Bruno Denis (Doxygen documentation and code rearrangement)
denis2nis 1:a9ba9cf928fe 80 *
denis2nis 5:0cf54586a4be 81 * @see Control table of Dynamixel MX12 servomotor
denis2nis 5:0cf54586a4be 82 * @see https://emanual.robotis.com/docs/en/dxl/mx/mx-12w/
denis2nis 5:0cf54586a4be 83 * @see Dynamixel protocol v1.0 manual
denis2nis 5:0cf54586a4be 84 * @see https://emanual.robotis.com/docs/en/dxl/protocol1/
denis2nis 5:0cf54586a4be 85 *
denis2nis 8:e74ef93ae660 86 * @warning
denis2nis 8:e74ef93ae660 87 *
denis2nis 8:e74ef93ae660 88 * Error field of status packet if decoded by GetStatus(() function which
denis2nis 8:e74ef93ae660 89 * returns an enumation type "Status". As several errors can be reported
denis2nis 8:e74ef93ae660 90 * simultaneously the type enum is not suitable (B. Denis 11/2021)
denis2nis 8:e74ef93ae660 91 *
denis2nis 8:e74ef93ae660 92 * _frame_pointer variable is used by _ReadCallback() ISR to store the
denis2nis 8:e74ef93ae660 93 * current size for message (status packet) received from servomotor.
denis2nis 8:e74ef93ae660 94 * This variable is NOT initialised and NEVER reset to zero at each new
denis2nis 8:e74ef93ae660 95 * message.
denis2nis 8:e74ef93ae660 96 *
denis2nis 1:a9ba9cf928fe 97 */
denis2nis 0:7556356a8bcd 98 class MX12
denis2nis 0:7556356a8bcd 99 {
denis2nis 0:7556356a8bcd 100 public:
denis2nis 0:7556356a8bcd 101
denis2nis 8:e74ef93ae660 102 /** Error status occurred during the operation of servomotor.
denis2nis 8:e74ef93ae660 103 *
denis2nis 8:e74ef93ae660 104 * @warning
denis2nis 8:e74ef93ae660 105 * Enumaration type is not suitable for all error status because
denis2nis 8:e74ef93ae660 106 * it can denote only one error at a time (B. Denis 11/2021)
denis2nis 8:e74ef93ae660 107 */
denis2nis 8:e74ef93ae660 108 enum Status {
denis2nis 8:e74ef93ae660 109 InstructionError, /**< In case of sending an undefined instruction
denis2nis 8:e74ef93ae660 110 or delivering the action instruction
denis2nis 8:e74ef93ae660 111 without the Reg Write instruction */
denis2nis 8:e74ef93ae660 112 OverloadError, /**< When the current load cannot be controlled
denis2nis 8:e74ef93ae660 113 by the set Torque */
denis2nis 8:e74ef93ae660 114 ChecksumError, /**< When the Checksum of the transmitted
denis2nis 8:e74ef93ae660 115 Instruction Packet is incorrect */
denis2nis 8:e74ef93ae660 116 RangeError, /**< When an instruction is out of the range
denis2nis 8:e74ef93ae660 117 for use */
denis2nis 8:e74ef93ae660 118 OverheatingError, /**< When internal temperature of servomotor
denis2nis 8:e74ef93ae660 119 is out of the range of operating
denis2nis 8:e74ef93ae660 120 temperature set in the Control table */
denis2nis 8:e74ef93ae660 121 AngleLimitError, /**< When Goal Position is written out of the
denis2nis 8:e74ef93ae660 122 range from CW Angle Limit to CCW Angle
denis2nis 8:e74ef93ae660 123 Limit */
denis2nis 8:e74ef93ae660 124 InputVoltageError, /**< When the applied voltage is out of the
denis2nis 8:e74ef93ae660 125 range of operating voltage set in the
denis2nis 8:e74ef93ae660 126 Control table */
denis2nis 8:e74ef93ae660 127 Unknown, /**< Combination of several errors (Caution:
denis2nis 8:e74ef93ae660 128 limit of enum approach to code errors) */
denis2nis 8:e74ef93ae660 129 Ok ///< no error
denis2nis 8:e74ef93ae660 130 };
denis2nis 8:e74ef93ae660 131
denis2nis 8:e74ef93ae660 132 /** State of packet parser to determine the meaning of reading byte
denis2nis 8:e74ef93ae660 133 * into the received packet (status packet) according the Dynamixel
denis2nis 8:e74ef93ae660 134 * protocol v1.0
denis2nis 8:e74ef93ae660 135 */
denis2nis 8:e74ef93ae660 136 enum ParsingState {
denis2nis 8:e74ef93ae660 137 Header, ///< reading the two heading bytes
denis2nis 8:e74ef93ae660 138 Id, ///< reading the servomotor ID byte
denis2nis 8:e74ef93ae660 139 Length, ///< reading byte length of the instruction
denis2nis 8:e74ef93ae660 140 Data, ///< reading parameters
denis2nis 8:e74ef93ae660 141 Checksum ///< reading one bytes checksum
denis2nis 8:e74ef93ae660 142 };
denis2nis 5:0cf54586a4be 143
denis2nis 8:e74ef93ae660 144 /** Enumeration of states of the acces methode of the master-slave
denis2nis 8:e74ef93ae660 145 * protocol of the communication between the robot controller (master)
denis2nis 8:e74ef93ae660 146 * and the servomotors (slaves).
denis2nis 8:e74ef93ae660 147 */
denis2nis 8:e74ef93ae660 148 enum SerialState {
denis2nis 8:e74ef93ae660 149 Writing, /**< Robot controller send an "instruction packet"
denis2nis 8:e74ef93ae660 150 (request) to a servomotor */
denis2nis 8:e74ef93ae660 151 Reading, /**< Robot controller receive a "status packet" from a
denis2nis 8:e74ef93ae660 152 requested servomotor */
denis2nis 8:e74ef93ae660 153 Idle ///< Robot controller ready for a new cycle request-answer
denis2nis 8:e74ef93ae660 154 };
denis2nis 8:e74ef93ae660 155
denis2nis 8:e74ef93ae660 156 /** Structure of store status packet (also known as return packet)
denis2nis 8:e74ef93ae660 157 * according tne Dynamixel protocol v1.0, which are messages sent
denis2nis 8:e74ef93ae660 158 * by servomotors to contriller in response of an instruction packet
denis2nis 8:e74ef93ae660 159 */
denis2nis 8:e74ef93ae660 160 struct Frame {
denis2nis 8:e74ef93ae660 161 unsigned char motorId; /**< Identifier of the servomotor involved
denis2nis 8:e74ef93ae660 162 in this exchange */
denis2nis 8:e74ef93ae660 163 unsigned char length; /**< */
denis2nis 8:e74ef93ae660 164 unsigned char data[MX12_DATA_MAX_SIZE]; /**< */
denis2nis 8:e74ef93ae660 165 unsigned char valid; /**< */
denis2nis 8:e74ef93ae660 166 };
denis2nis 8:e74ef93ae660 167
denis2nis 8:e74ef93ae660 168 /**
denis2nis 8:e74ef93ae660 169 */
denis2nis 8:e74ef93ae660 170 struct StateContext {
denis2nis 8:e74ef93ae660 171 unsigned char headingCount;
denis2nis 8:e74ef93ae660 172 unsigned char dataCount;
denis2nis 8:e74ef93ae660 173 unsigned char checksum;
denis2nis 8:e74ef93ae660 174 };
denis2nis 5:0cf54586a4be 175
denis2nis 8:e74ef93ae660 176 /** Create MX12 instance
denis2nis 8:e74ef93ae660 177 *
denis2nis 8:e74ef93ae660 178 * @param tx board pin used for transmission in UART daisy chain link
denis2nis 8:e74ef93ae660 179 * to servomotors
denis2nis 8:e74ef93ae660 180 * @param rx board pin used for reception in UART daisy chain link
denis2nis 8:e74ef93ae660 181 * to servomotors
denis2nis 8:e74ef93ae660 182 * @param baud modulation rate of UART signal, unit: Baud
denis2nis 8:e74ef93ae660 183 * to servomotors
denis2nis 8:e74ef93ae660 184 */
denis2nis 8:e74ef93ae660 185 MX12(PinName tx, PinName rx, int baud=115200);
denis2nis 8:e74ef93ae660 186
denis2nis 8:e74ef93ae660 187 /** Send desired speed to a specific servomotor
denis2nis 8:e74ef93ae660 188 *
denis2nis 8:e74ef93ae660 189 * @param mot_id a unique value in the daisy chain network to identify
denis2nis 8:e74ef93ae660 190 * each servomotor
denis2nis 8:e74ef93ae660 191 * @param speed a float between -1 and 1 that represents the percentage
denis2nis 8:e74ef93ae660 192 * of maximum requested speed
denis2nis 8:e74ef93ae660 193 */
denis2nis 8:e74ef93ae660 194 void SetSpeed(unsigned char mot_id, float speed);
denis2nis 8:e74ef93ae660 195
denis2nis 8:e74ef93ae660 196 char IsAvailable(void);
denis2nis 8:e74ef93ae660 197
denis2nis 8:e74ef93ae660 198 /**
denis2nis 8:e74ef93ae660 199 * Build and send an instruction packet to a servomotor according
denis2nis 8:e74ef93ae660 200 * DYNAMIXEL Protocol 1.0 (online protocol documentation
denis2nis 8:e74ef93ae660 201 * https://emanual.robotis.com/docs/en/dxl/protocol1/)
denis2nis 8:e74ef93ae660 202 *
denis2nis 8:e74ef93ae660 203 * @param[in] mot_id indicates the ID of the device (servomotor) that
denis2nis 8:e74ef93ae660 204 * should receive the Instruction Packet and process it
denis2nis 8:e74ef93ae660 205 * @param[in] address data address in the "Control Table of RAM Area"
denis2nis 8:e74ef93ae660 206 * of a servomotor MX12
denis2nis 8:e74ef93ae660 207 * (https://emanual.robotis.com/docs/en/dxl/mx/mx-12w/#control-table-of-ram-area).
denis2nis 8:e74ef93ae660 208 * @param[in] len if it is a write instruction, size in bytes
denis2nis 8:e74ef93ae660 209 * of the data to write in the "Control Table of RAM Area"
denis2nis 8:e74ef93ae660 210 * @param[in] data array of char containing parameter of Danamixel
denis2nis 8:e74ef93ae660 211 * protocol that are the instruction’s auxiliary data field
denis2nis 8:e74ef93ae660 212 *
denis2nis 8:e74ef93ae660 213 * @see https://emanual.robotis.com/docs/en/dxl/protocol1/
denis2nis 8:e74ef93ae660 214 *
denis2nis 8:e74ef93ae660 215 * Packet sent
denis2nis 8:e74ef93ae660 216 * <PRE>
denis2nis 8:e74ef93ae660 217 * |Header1|Header2|Packet ID|Length|Instruction|Param1...ParamN|Checksum|
denis2nis 8:e74ef93ae660 218 * |-------|-------|---------|------|-----------|---------------|--------|
denis2nis 8:e74ef93ae660 219 * | 0xFF | 0xFF |Packet ID|Length|Instruction|Param1...ParamN| CHKSUM |
denis2nis 8:e74ef93ae660 220 * | cmd[0]| cmd[1]| cmd[2] |cmd[3]| cmd[4] |cmd[5]... | |
denis2nis 8:e74ef93ae660 221 * \\__ ___/ \\_ _/ \\__ __/
denis2nis 8:e74ef93ae660 222 * \/ \/ \/
denis2nis 8:e74ef93ae660 223 * mot_id address data
denis2nis 8:e74ef93ae660 224 * (len = N-1)
denis2nis 8:e74ef93ae660 225 * </PRE>
denis2nis 8:e74ef93ae660 226 */
denis2nis 8:e74ef93ae660 227 void rw(unsigned char mot_id, char address, char len, char *data);
denis2nis 8:e74ef93ae660 228
denis2nis 8:e74ef93ae660 229 /**
denis2nis 8:e74ef93ae660 230 *
denis2nis 8:e74ef93ae660 231 * @warning
denis2nis 8:e74ef93ae660 232 *
denis2nis 8:e74ef93ae660 233 */
denis2nis 8:e74ef93ae660 234 void PrintSerial();
denis2nis 8:e74ef93ae660 235
denis2nis 8:e74ef93ae660 236 /**
denis2nis 8:e74ef93ae660 237 * Get information from de Error byte of the last status packet
denis2nis 8:e74ef93ae660 238 * received from a servomotor
denis2nis 8:e74ef93ae660 239 *
denis2nis 8:e74ef93ae660 240 * @return
denis2nis 8:e74ef93ae660 241 * One of enum MX12::Status value to describe errors. 'Ok' is
denis2nis 8:e74ef93ae660 242 * returns if no error occurred during the last operation of
denis2nis 8:e74ef93ae660 243 * servomotor.
denis2nis 8:e74ef93ae660 244 *
denis2nis 8:e74ef93ae660 245 * @warning
denis2nis 8:e74ef93ae660 246 * If a combination of several errors is reported the function
denis2nis 8:e74ef93ae660 247 * returns 'Unknown' (B. Denis 11/2021)
denis2nis 8:e74ef93ae660 248 */
denis2nis 8:e74ef93ae660 249 MX12::Status GetStatus(void);
denis2nis 5:0cf54586a4be 250
denis2nis 8:e74ef93ae660 251 /* function aivailaible in a previous version of the class
denis2nis 8:e74ef93ae660 252 */
denis2nis 8:e74ef93ae660 253 // MX12::Status GetStatus(void);
denis2nis 8:e74ef93ae660 254 // void ReadPosition(unsigned char mot_id);
denis2nis 8:e74ef93ae660 255 // float GetPosition(unsigned char mot_id);
denis2nis 8:e74ef93ae660 256 int get_counter();
denis2nis 8:e74ef93ae660 257
denis2nis 8:e74ef93ae660 258
denis2nis 5:0cf54586a4be 259 private:
denis2nis 5:0cf54586a4be 260
denis2nis 8:e74ef93ae660 261 UnbufferedSerial _mx12;
denis2nis 8:e74ef93ae660 262 MX12::ParsingState _pstate;
denis2nis 8:e74ef93ae660 263 MX12::SerialState _sstate;
denis2nis 8:e74ef93ae660 264
denis2nis 8:e74ef93ae660 265 /** Structure used only by ISR (Interrupt Service Routine) ReadCallback()
denis2nis 8:e74ef93ae660 266 *
denis2nis 8:e74ef93ae660 267 */
denis2nis 8:e74ef93ae660 268 MX12::StateContext _scontext;
denis2nis 8:e74ef93ae660 269 MX12::Frame _current_frame;
denis2nis 8:e74ef93ae660 270
denis2nis 8:e74ef93ae660 271 unsigned char _answer;
denis2nis 8:e74ef93ae660 272
denis2nis 8:e74ef93ae660 273 /** Character array to store status message received from servomotors.
denis2nis 8:e74ef93ae660 274 * _ReadCallback() ISR fill this array character by character and
denis2nis 8:e74ef93ae660 275 * update the size of the message currently received in the variable
denis2nis 8:e74ef93ae660 276 * _frame_pointer.
denis2nis 8:e74ef93ae660 277 */
denis2nis 8:e74ef93ae660 278 unsigned char _stored_frame[MX12_DATA_MAX_SIZE];
denis2nis 8:e74ef93ae660 279
denis2nis 8:e74ef93ae660 280 /** Size of the message currently received from servomotor. This variable
denis2nis 8:e74ef93ae660 281 * is update at each call of _ReadCallback() ISR. The content of the
denis2nis 8:e74ef93ae660 282 * message is store into _stored_frame array.
denis2nis 8:e74ef93ae660 283 *
denis2nis 8:e74ef93ae660 284 * @warning
denis2nis 8:e74ef93ae660 285 */
denis2nis 8:e74ef93ae660 286 unsigned char _frame_pointer;
denis2nis 8:e74ef93ae660 287
denis2nis 8:e74ef93ae660 288 volatile int _BDcount;
denis2nis 8:e74ef93ae660 289
denis2nis 8:e74ef93ae660 290 /** Interupt service routine (ISR) to read and parse the response message
denis2nis 8:e74ef93ae660 291 * comming from servomotor on UART (serial port). This routine is called
denis2nis 8:e74ef93ae660 292 * when each character is received on the servomotor bus.
denis2nis 8:e74ef93ae660 293 *
denis2nis 8:e74ef93ae660 294 * As the characters are received, the progress of the parser
denis2nis 8:e74ef93ae660 295 * is stored in the two state variables _pstate and _scontext,
denis2nis 8:e74ef93ae660 296 * and the result of the analysis is stored in _current_frame.
denis2nis 8:e74ef93ae660 297 */
denis2nis 8:e74ef93ae660 298 void _ReadCallback();
denis2nis 8:e74ef93ae660 299
denis2nis 8:e74ef93ae660 300 void _Rx_BD_interrupt();
denis2nis 8:e74ef93ae660 301
denis2nis 0:7556356a8bcd 302 };
denis2nis 0:7556356a8bcd 303
denis2nis 8:e74ef93ae660 304 #endif /* MBED_MX12_H_ */