Reformat and extend comments

README.md

@@ -1,9 +1,7 @@
-CAN BUS Shield
+# CAN BUS Shield
----------------------------------------------------------
+---
 [![CAN BUS Shield](https://statics3.seeedstudio.com/seeed/file/2017-08/bazaar528529_img_2653a.jpg)](https://www.seeedstudio.com/CAN-BUS-Shield-V2-p-2921.html)
 
-<br>
-
 CAN-BUS is a common industrial bus because of its long travel distance, medium communication speed and high reliability. It is commonly found on modern machine tools and as an automotive diagnostic bus. This CAN-BUS Shield adopts MCP2515 CAN Bus controller with SPI interface and MCP2551 CAN transceiver to give your Arduino/Seeeduino CAN-BUS capability. With an OBD-II converter cable added on and the OBD-II library imported, you are ready to build an onboard diagnostic device or data logger.
 
 - Implements CAN V2.0B at up to 1 Mb/s

mcp_can.cpp

@@ -192,7 +192,7 @@ byte MCP_CAN::mcp2515_readRegister(const byte address)
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_readRegisterS
-** Descriptions:            read registerS
+** Descriptions:            read sucessive registers
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_readRegisterS(const byte address, byte values[], const byte n)
 {
@@ -235,7 +235,7 @@ void MCP_CAN::mcp2515_setRegister(const byte address, const byte value)
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_setRegisterS
-** Descriptions:            set registerS
+** Descriptions:            set sucessive registers
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_setRegisterS(const byte address, const byte values[], const byte n)
 {
@@ -259,7 +259,7 @@ void MCP_CAN::mcp2515_setRegisterS(const byte address, const byte values[], cons
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_modifyRegister
-** Descriptions:            set bit of one register
+** Descriptions:            Sets specific bits of a register
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_modifyRegister(const byte address, const byte mask, const byte data)
 {
@@ -279,7 +279,7 @@ void MCP_CAN::mcp2515_modifyRegister(const byte address, const byte mask, const
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_readStatus
-** Descriptions:            read mcp2515's Status
+** Descriptions:            read mcp2515's status register
 *********************************************************************************************************/
 byte MCP_CAN::mcp2515_readStatus(void)
 {
@@ -551,7 +551,7 @@ byte MCP_CAN::mcp2515_configRate(const byte canSpeed, const byte clock)
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_initCANBuffers
-** Descriptions:            init canbuffers
+** Descriptions:            initialize CAN buffers
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_initCANBuffers(void)
 {
@@ -575,7 +575,7 @@ void MCP_CAN::mcp2515_initCANBuffers(void)
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_init
-** Descriptions:            init the device
+** Descriptions:            initialize the controller
 *********************************************************************************************************/
 byte MCP_CAN::mcp2515_init(const byte canSpeed, const byte clock)
 {
@@ -694,7 +694,7 @@ void mcp2515_id_to_buf(const byte ext, const unsigned long id, byte *tbufdata)
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_write_id
-** Descriptions:            write can id
+** Descriptions:            write CAN ID
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_write_id(const byte mcp_addr, const byte ext, const unsigned long id)
 {
@@ -706,7 +706,7 @@ void MCP_CAN::mcp2515_write_id(const byte mcp_addr, const byte ext, const unsign
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_read_id
-** Descriptions:            read can id
+** Descriptions:            read CAN ID
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_read_id(const byte mcp_addr, byte* ext, unsigned long* id)
 {
@@ -731,7 +731,7 @@ void MCP_CAN::mcp2515_read_id(const byte mcp_addr, byte* ext, unsigned long* id)
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_write_canMsg
-** Descriptions:            write msg
+** Descriptions:            write message
 **                          Note! There is no check for right address!
 *********************************************************************************************************/
 void MCP_CAN::mcp2515_write_canMsg(const byte buffer_sidh_addr, unsigned long id, byte ext, byte rtrBit, byte len, volatile const byte *buf)
@@ -816,7 +816,7 @@ void MCP_CAN::mcp2515_start_transmit(const byte mcp_addr)              // start
 
 /*********************************************************************************************************
 ** Function name:           mcp2515_isTXBufFree
-** Descriptions:            Test is tx buffer free for transmitting
+** Descriptions:            Test if tx buffer is free for transmitting
 *********************************************************************************************************/
 byte MCP_CAN::mcp2515_isTXBufFree(byte *txbuf_n, byte iBuf)           /* get Next free txbuf          */
 {
@@ -1109,7 +1109,7 @@ byte MCP_CAN::sendMsg(unsigned long id, byte ext, byte rtrBit, byte len, const b
 
 /*********************************************************************************************************
 ** Function name:           sendMsgBuf
-** Descriptions:            send buf
+** Descriptions:            Send message to transmitt buffer
 *********************************************************************************************************/
 byte MCP_CAN::sendMsgBuf(unsigned long id, byte ext, byte rtrBit, byte len, const byte *buf, bool wait_sent)
 {
@@ -1118,7 +1118,7 @@ byte MCP_CAN::sendMsgBuf(unsigned long id, byte ext, byte rtrBit, byte len, cons
 
 /*********************************************************************************************************
 ** Function name:           sendMsgBuf
-** Descriptions:            send buf
+** Descriptions:            Send message to transmitt buffer
 *********************************************************************************************************/
 byte MCP_CAN::sendMsgBuf(unsigned long id, byte ext, byte len, const byte *buf, bool wait_sent)
 {
@@ -1128,7 +1128,7 @@ byte MCP_CAN::sendMsgBuf(unsigned long id, byte ext, byte len, const byte *buf,
 
 /*********************************************************************************************************
 ** Function name:           readMsgBuf
-** Descriptions:            read message buf
+** Descriptions:            read message from receive buffer
 *********************************************************************************************************/
 byte MCP_CAN::readMsgBuf(byte *len, byte buf[])
 {
@@ -1137,7 +1137,7 @@ byte MCP_CAN::readMsgBuf(byte *len, byte buf[])
 
 /*********************************************************************************************************
 ** Function name:           readMsgBufID
-** Descriptions:            read message buf and can bus source ID
+** Descriptions:            read message buffer and CAN bus source ID
 *********************************************************************************************************/
 byte MCP_CAN::readMsgBufID(unsigned long *ID, byte *len, byte buf[])
 {
@@ -1251,7 +1251,7 @@ void MCP_CAN::clearBufferTransmitIfFlags(byte flags)
 
 /*********************************************************************************************************
 ** Function name:           checkReceive
-** Descriptions:            check if got something
+** Descriptions:            check if a message was arrived
 *********************************************************************************************************/
 byte MCP_CAN::checkReceive(void)
 {
@@ -1262,7 +1262,7 @@ byte MCP_CAN::checkReceive(void)
 
 /*********************************************************************************************************
 ** Function name:           checkError
-** Descriptions:            if something error
+** Descriptions:            check if an error occurred
 *********************************************************************************************************/
 byte MCP_CAN::checkError(void)
 {
@@ -1272,7 +1272,7 @@ byte MCP_CAN::checkError(void)
 
 /*********************************************************************************************************
 ** Function name:           getCanId
-** Descriptions:            when receive something, you can get the can id!!
+** Descriptions:            return CAN ID of last message
 *********************************************************************************************************/
 unsigned long MCP_CAN::getCanId(void)
 {
@@ -1281,7 +1281,7 @@ unsigned long MCP_CAN::getCanId(void)
 
 /*********************************************************************************************************
 ** Function name:           isRemoteRequest
-** Descriptions:            when receive something, you can check if it was a request
+** Descriptions:            check if last message was a remote request
 *********************************************************************************************************/
 byte MCP_CAN::isRemoteRequest(void)
 {
@@ -1290,7 +1290,7 @@ byte MCP_CAN::isRemoteRequest(void)
 
 /*********************************************************************************************************
 ** Function name:           isExtendedFrame
-** Descriptions:            did we just receive standard 11bit frame or extended 29bit? 0 = std, 1 = ext
+** Descriptions:            check if last message used standard 11bit or extended 29bit address. 0 = std, 1 = ext
 *********************************************************************************************************/
 byte MCP_CAN::isExtendedFrame(void)
 {
@@ -1299,4 +1299,4 @@ byte MCP_CAN::isExtendedFrame(void)
 
 /*********************************************************************************************************
   END FILE
-*********************************************************************************************************/
+*********************************************************************************************************/

mcp_can.h

@@ -55,13 +55,13 @@ class MCP_CAN
 {
     private:
 
-    byte   ext_flg;                         // identifier xxxID
+    byte   ext_flg;                         // Identifier Type
-                                            // either extended (the 29 LSB) or standard (the 11 LSB)
+                                            // Extended (29 bit) or Standard (11 bit)
-    unsigned long  can_id;                  // can id
+    unsigned long  can_id;                  // CAN ID
-    byte   rtr;                             // rtr
+    byte   rtr;                             // Remote request flag
-    byte   SPICS;
+    byte   SPICS;                           // Chip Select pin number
     SPIClass *pSPI;
-    byte   nReservedTx;                     // Count of tx buffers for reserved send
+    byte   nReservedTx;                     // Number of tx buffers reserved for send
 
 /*
 *  mcp2515 driver function
@@ -71,42 +71,42 @@ private:
 
     void mcp2515_reset(void);                                   // reset mcp2515
 
-    byte mcp2515_readRegister(const byte address);              // read mcp2515's register
+    byte mcp2515_readRegister(const byte address);              // read mcp2515 register
 
     void mcp2515_readRegisterS(const byte address,
 	                       byte values[],
                                const byte n);
-    void mcp2515_setRegister(const byte address,                // set mcp2515's register
+    void mcp2515_setRegister(const byte address,                // set mcp2515 register
                              const byte value);
 
-    void mcp2515_setRegisterS(const byte address,               // set mcp2515's registers
+    void mcp2515_setRegisterS(const byte address,               // set successive mcp2515 registers
                               const byte values[],
                               const byte n);
 
     void mcp2515_initCANBuffers(void);
 
-    void mcp2515_modifyRegister(const byte address,             // set bit of one register
+    void mcp2515_modifyRegister(const byte address,             // Set specific bit(s) of a register
                                 const byte mask,
                                 const byte data);
 
-    byte mcp2515_readStatus(void);                              // read mcp2515's Status
+    byte mcp2515_readStatus(void);                              // read mcp2515 status
     byte mcp2515_setCANCTRL_Mode(const byte newmode);           // set mode
     byte mcp2515_configRate(const byte canSpeed, const byte clock);  // set baudrate
-    byte mcp2515_init(const byte canSpeed, const byte clock);   // mcp2515init
+    byte mcp2515_init(const byte canSpeed, const byte clock);   // Initialize Controller
 
-    void mcp2515_write_id( const byte mcp_addr,                 // write can id
+    void mcp2515_write_id( const byte mcp_addr,                 // write CAN ID
                                const byte ext,
                                const unsigned long id );
 
-    void mcp2515_read_id( const byte mcp_addr,                  // read can id
+    void mcp2515_read_id( const byte mcp_addr,                  // read CAN ID
                                     byte* ext,
                                     unsigned long* id );
 
-    void mcp2515_write_canMsg( const byte buffer_sidh_addr, unsigned long id, byte ext, byte rtr, byte len, volatile const byte *buf);     // read can msg
+    void mcp2515_write_canMsg( const byte buffer_sidh_addr, unsigned long id, byte ext, byte rtr, byte len, volatile const byte *buf);     // write CAN msg
-    void mcp2515_read_canMsg( const byte buffer_load_addr, volatile unsigned long *id, volatile byte *ext, volatile byte *rtr, volatile byte *len, volatile byte *buf);   // write can msg
+    void mcp2515_read_canMsg( const byte buffer_load_addr, volatile unsigned long *id, volatile byte *ext, volatile byte *rtr, volatile byte *len, volatile byte *buf);   // read CAN msg
-    void mcp2515_start_transmit(const byte mcp_addr);           // start transmit
+    void mcp2515_start_transmit(const byte mcp_addr);           // start transmission
-    byte mcp2515_getNextFreeTXBuf(byte *txbuf_n);               // get Next free txbuf
+    byte mcp2515_getNextFreeTXBuf(byte *txbuf_n);               // Find empty transmit buffer
-    byte mcp2515_isTXBufFree(byte *txbuf_n, byte iBuf);         // is buffer by index free
+    byte mcp2515_isTXBufFree(byte *txbuf_n, byte iBuf);         // Check if specified buffer is free
 
 /*
 *  can operator function
@@ -129,10 +129,10 @@ public:
     byte sendMsgBuf(unsigned long id, byte ext, byte len, const byte *buf, bool wait_sent=true);               // send buf
     byte readMsgBuf(byte *len, byte *buf);                          // read buf
     byte readMsgBufID(unsigned long *ID, byte *len, byte *buf);     // read buf with object ID
-    byte checkReceive(void);                                        // if something received
+    byte checkReceive(void);                                        // check if a message was received
-    byte checkError(void);                                          // if something error
+    byte checkError(void);                                          // check if an error occurred
-    unsigned long getCanId(void);                                   // get can id when receive
+    unsigned long getCanId(void);                                   // return CAN ID of last message
-    byte isRemoteRequest(void);                                     // get RR flag when receive
+    byte isRemoteRequest(void);                                     // check if last message was a remote request
     byte isExtendedFrame(void);                                     // did we recieve 29bit frame?
 
     byte readMsgBufID(byte status, volatile unsigned long *id, volatile byte *ext, volatile byte *rtr, volatile byte *len, volatile byte *buf); // read buf with object ID

mcp_can_dfs.h

@@ -448,4 +448,4 @@
 #endif
 /*********************************************************************************************************
   END FILE
-*********************************************************************************************************/
+*********************************************************************************************************/