Page 1 of 1

Arduino Library, Documentation, and Updates

Posted: Thu Jan 09, 2020 4:03 am
by JorgeP
I have been working on my project again, after a long hiatus, due to a new baby.

I have been interested in documenting and updating the Arduino Library and have started with the un-named enum at the beginning of RoboClaw.h. I have modified it in the following way.

(Doing all this, as described below, will most likely break current code and require rewriting of end user code. So an alternate library should be derived from the current one as an example)

Code: Select all

  enum {
      M1FORWARD                 =   0, // Drive Forward Motor 1
      M1BACKWARD                =   1, // Drive Backword Motor 1
      SETMINMB                  =   2, // (COMMAND 57 PREFERED) Set Main Voltage Minimum
      SETMAXMB                  =   3, // (COMMAND 57 PREFERED) Set Main Voltage Maximum
      M2FORWARD                 =   4, // Drive Forward Motor 2
      M2BACKWARD                =   5, // Drive Backward Motor 2
      M17BIT                    =   6, // Drive Motor 1 (7 bit)
      M27BIT                    =   7, // Drive Motor 2 (7 bit)
      MIXEDFORWARD              =   8, // Drive Forward Mixed Mode
      MIXEDBACKWARD             =   9, // Drive Backwards Mixed Mode
      MIXEDRIGHT                =  10, // Turn Right Mixed Mode
      MIXEDLEFT                 =  11, // Turn Left Mixed Mode
      MIXEDFB                   =  12, // Drive Forward or Backword (7 bit)
      MIXEDLR                   =  13, // Turn Left or Right (7 bit)
      
      GETM1ENC                  =  16, // Get M1 Encoder Count/Value
      GETM2ENC                  =  17, // Get M2 Encoder Count/Value
      GETM1SPEED                =  18, // Get M1 Speed in Encoder Counts Per Second
      GETM2SPEED                =  19, // Get M2 Speed in Encoder Counts Per Second
      RESETENC                  =  20, // Reset Encoder Registers for M1 and M2 (Quadrature only)
      GETVERSION                =  21, // Read Firmware Version
      SETM1ENCCOUNT             =  22, // Set Encoder 1 Register (Quadrature only)
      SETM2ENCCOUNT             =  23, // Set Encoder 2 Register (Quadrature only)
      GETMBATT                  =  24, // Read Main Battery Voltage
      GETLBATT                  =  25, // Read Logic Battery Voltage
      SETMINLB                  =  26, // Set Minimum Logic Voltage Level
      SETMAXLB                  =  27, // Set Maximum Logic Voltage Level
      SETM1PID                  =  28, // Set M1 Velocity PID Constants
      SETM2PID                  =  29, // Set M2 Velocity PID Constants
      GETM1ISPEED               =  30, // Get Current (I) M1 Raw Speed
      GETM2ISPEED               =  31, // Get Current (I) M2 Raw Spead
      M1DUTY                    =  32, // Drive M1 with Signed Duty Cycle (Encoders Not Required)
      M2DUTY                    =  33, // Drive M2 with Signed Duty Cycle (Encoders Not Required)
      MIXEDDUTY                 =  34, // Drive M1/M2 with Signed Duty Cycle (Encoders Not Required)
      M1SPEED                   =  35, // Drive M1 with Signed Speed
      M2SPEED                   =  36, // Drive M2 with Signed Speed
      MIXEDSPEED                =  37, // Drive M1/M2 with Signed Speed
      M1SPEEDACCEL              =  38, // Drive M1 with Signed Speed and Acceleration
      M2SPEEDACCEL              =  39, // Drive M2 with Signed Speed and Acceleration
      MIXEDSPEEDACCEL           =  40, // Drive M1/M2 with Signed Speed and Acceleration
      M1SPEEDDIST               =  41, // Drive M1 with Signed Speed and Distance (Buffered)
      M2SPEEDDIST               =  42, // Drive M2 with Signed Speed and Distance (Buffered)
      MIXEDSPEEDDIST            =  43, // Drive M1/M2 with Signed Speed and Distance (Buffered)
      M1SPEEDACCELDIST          =  44, // Drive M1 with Signed Speed, Acceleration, and Distance (Buffered)
      M2SPEEDACCELDIST          =  45, // Drive M2 with Signed Speed, Acceleration, and Distance (Buffered)
      MIXEDSPEEDACCELDIST       =  46, // Drive M1/M2 with Signed Speed, Acceleration, and Distance (Buffered)
      GETBUFFERS                =  47, // Get Buffer Length
      GETPWMS                   =  48, // Get Motor PWMs
      GETCURRENTS               =  49, // Get Motor Currents (I)
      MIXEDSPEED2ACCEL          =  50, // Drive M1/M2 with Individual Signed Speed and Acceleration
      MIXEDSPEED2ACCELDIST      =  51, // Drive M1/M2 with Individual Signed Speed, Acceleration, and Distance
      M1DUTYACCEL               =  52, // Drive M1 with Signed Duty and Acceleration (Encoders Not Required)
      M2DUTYACCEL               =  53, // Drive M2 with Signed Duty and Acceleration (Encoders Not Required)
      MIXEDDUTYACCEL            =  54, // Drive M1/M2 with Signed Duty and Acceleration (Encoders Not Required)
      READM1PID                 =  55, // Get M1 Velocity PID Constants
      READM2PID                 =  56, // Get M2 Velocity PID Constants
      SETMAINVOLTAGES           =  57, // Set Main Battery Voltages
      SETLOGICVOLTAGES          =  58, // Set Logic Battery Voltages
      GETMINMAXMAINVOLTAGES     =  59, // Read Main Battery Voltage Settings
      GETMINMAXLOGICVOLTAGES    =  60, // Read Logic Battery Voltage Settings
      SETM1POSPID               =  61, // Set M1 Position PID Constants
      SETM2POSPID               =  62, // Set M2 Position PID Constants
      READM1POSPID              =  63, // Get M1 Position PID Constants
      READM2POSPID              =  64, // Get M2 Position PID Constants
      M1SPEEDACCELDECCELPOS     =  65, // Drive M1 with Speed, Acceleration, Deceleration, and Position
      M2SPEEDACCELDECCELPOS     =  66, // Drive M2 with Speed, Acceleration, Deceleration, and Position
      MIXEDSPEEDACCELDECCELPOS  =  67, // Drive M1/M2 with Speed, Acceleration, Deceleration, and Position
      SETM1DEFAULTACCEL         =  68, // Set M1 Default Duty Acceleration
      SETM2DEFAULTACCEL         =  69, // Set M2 Default Duty Acceleration
      
      SETPINFUNCTIONS           =  74, // Set S3, S4 and S5 Modes (Only Documented on Robolaw Models, unknown on MCP)
      GETPINFUNCTIONS           =  75, // Get S3, S4 and S5 Modes (Only Documented on Robolaw Models, unknown on MCP)
      SETDEADBAND               =  76, // Set DeadBand for RC/Analog controls (Only Documented on Robolaw Models, unknown on MCP)
      GETDEADBAND               =  77, // Get DeadBand for RC/Analog controls (Only Documented on Robolaw Models, unknown on MCP)
      GETENCODERS               =  78, // Read Encoders Counts 
      GETISPEEDS                =  79, // Get Motors Speeds
      RESTOREDEFAULTS           =  80, // Restore Defaults

                                       // 81 = Read Default Duty Acceleration Settings
      
      GETTEMP                   =  82, // Read Temperature
      GETTEMP2                  =  83, // Read Temperature 2
      
      GETERROR                  =  90, // Read Status
      GETENCODERMODE            =  91, // Read Encoder Modes
      SETM1ENCODERMODE          =  92, // Set Motor 1 Encoder Mode
      SETM2ENCODERMODE          =  93, // Set Motor 2 Encoder Mode
      WRITENVM                  =  94, // Write Settings to EEPROM
      READNVM                   =  95, // Read Settings from EEPROM
      
      SETCONFIG                 =  98, // Set Standard Config Settings (Only Documented on Roboclaw, Unknown on MCP)
      GETCONFIG                 =  99, // Set Standard Config Settings (Only Documented on Roboclaw, Unknown on MCP)

                                       // 100 = Set CTRL Modes (Only Documented on Roboclaw, Unknown on MCP)
                                       // 101 = Get CTRL Modes (Only Documented on Roboclaw, Unknown on MCP)
                                       // 102 = Set CTRL1 (Only Documented on Robolaw Models, unknown on MCP)
                                       // 103 = Set CTRL2 (Only Documented on Robolaw Models, unknown on MCP)
                                       // 104 = Get CTRL Settings (Only Documented on Robolaw Models, unknown on MCP)

                                       // 128 = Set M1 Inductance and Resistance
                                       // 129 = Set M2 Inductance and Resistance
                                       // 130 = Get M1 Inductance and Resistance
                                       // 131 = Get M2 Inductance and Resistance
      
      SETM1MAXCURRENT           = 133, // Set M1 Maximum Current
      SETM2MAXCURRENT           = 134, // Set M2 Maximum Current
      GETM1MAXCURRENT           = 135, // Read M1 Maximum Current
      GETM2MAXCURRENT           = 136, // Read M2 Maximum Current

                                       // 137 = Set DOUT Actions
                                       // 138 = Get DOUT Actions
                                       // 139 = Set Priority Levels
                                       // 140 = Get Priority Levels
                                       // 141 = Set Address and Mixed Flags
                                       // 142 = Get Mixed Flag
                                       // 143 = Set Signal Properties
                                       // 144 = Get All Signal Properties
                                       // 145 = Set Stream Properties
                                       // 146 = Get All Stream Properties
                                       // 147 = Get Signal Values
      
      SETPWMMODE                = 148, // Set PWM Mode
      GETPWMMODE                = 149, // Get PWM Mode

                                       // 200 = E-Stop Reset
                                       // 201 = Lock/Unlock E-Stop Reset
                                       // 202 = Get E-Stop Lock

                                       // 246 = Set Script Autorun Delay
                                       // 247 = Get Script Autorun Delay
                                       // 248 = Start Script
                                       // 249 = Stop Script

                                       // 252 = Get User NVM Word
                                       // 253 = Set User NVM Word
      
      FLAGBOOTLOADER            = 255  // 
};  //end enum
There are several undocumented commands in the MCP manual, but Documented in the RoboClaw manuals, and vice versa. Some commands are not documented at all, that I can find. It seems that the Arduino Library was created specifically for the RoboClaw devices and not initially intended for the MCP devices.

I feel that the enum should be constants instead and labled/prefixed to something more appropriate, like BM (BasicMicro, for Universal Commands), RC (For Roboclaw Specific Commands), and MCP (For MCP Specific Commands), so I am going to make updates and start testing over the next few weeks/months.

Also, I have noticed in the original code (Not a complaint, Great thanks to its writer for sharing) that the wording Read/Write and Get/Set seem to be mixed throughout the code and should be changed to the GET/SET form to be kept consistent, and it is shorter. I would have to say the same for the Manuals.

I am only a user of the MCP devices so I cannot test the RoboClaw commands that are not documented for the MCP devices.

I would also like to create more library files to keep things organized a bit. For instance... BasicMicro.h/.cpp for universal commands available on all devices, RoboClaw.h/.cpp for RoboClaw Specific Commands, and MCP.h/.cpp for MCP Specific commands.

It also seams that the library should have Structs defined for getting/setting properties and values from the devices, I am just learning c but have experience in other languages, so... I imagine it will take me some time to get this done. I need this done for myself so I might as well share.

I am not proficient in GIT aside from clone and pull so I cannot update the new repositories on github. I am not too willing to learn git since I have my hands full with learning c and my projects. I can however provide diffs for someone to look over and patch the sources, although it has been quite some time since I produced any, it should come back to me fairly easily.

I've also formatted the code (comments) somewhat, so I can browse through and read it easier.

Regarding Documentation: I am interested in obtaining copies of Currently Un-Published Updates to the manuals for the MCP devices. If there is better information in those documents then I can update the code with comments that are better descriptive.

Re: Arduino Library, Documentation, and Updates

Posted: Thu Jan 09, 2020 12:50 pm
by Basicmicro Tech
Hi,

I'm BasicMicro's technical writer, I maintain the documentation and tutorials as well as write example code and maintain the GitHub repository. We would like to work with you as you make the changes you see fit for an alternate library that is documented in the source code.

We are planning a re-write of the MCP manual in the near future and are mostly finished with a re-write of the RoboClaw manual. One of the big changes in both re-writes is adding documentation so that the manual reflects the changes in the libraries.

I'll PM you my contact details so you can get a hold of me easily. I can help provide you with any additional information you need for your changes as well as manage adding your code to the appropriate GitHub repository.

Hope to hear from you soon.