Revision 2:37fafd1e1a20, committed 2010-07-13

Comitter:

donatien

Date:

Tue Jul 13 16:11:29 2010 +0000

Parent:

1:e96aaf4d5c55

Child:

3:60db4ab4dafe

Commit message:

Changed in this revision

--- a/RWDModule.cpp	Tue Jul 13 10:37:26 2010 +0000
+++ b/RWDModule.cpp	Tue Jul 13 16:11:29 2010 +0000
@@ -1,11 +1,35 @@
+
+/*
+Copyright (c) 2010 Donatien Garnier (donatiengar [at] gmail [dot] com)
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
 #include "RWDModule.h"
 
 RWDModule::RWDModule(PinName tx, PinName rx, PinName cts) : m_serial(tx, rx), m_cts(cts),
 m_cmd(0), m_paramsBuf(NULL), m_respBuf(NULL), m_pos(0), m_paramsLen(0), m_respLen(0), m_ackOk(0), m_ackOkMask(0), m_ack(0), m_state(READY)
 {
-  m_serial.attach(this, &RWDModule::intTx, Serial::TxIrq);
-  m_serial.attach(this, &RWDModule::intRx, Serial::RxIrq);
-  m_cts.fall(this, &RWDModule::intClearToSend);
+  //Setup interrupts
+  m_serial.attach(this, &RWDModule::intTx, Serial::TxIrq); //Serial port writeable
+  m_serial.attach(this, &RWDModule::intRx, Serial::RxIrq); //Serial port readable
+  m_cts.fall(this, &RWDModule::intClearToSend); //Clear To Send: can send a command
 }
 
 RWDModule::~RWDModule()
@@ -13,49 +37,50 @@
 
 }
 
-void RWDModule::command(byte cmd, const byte* params, int paramsLen, byte* resp, int respLen, byte ackOk, byte ackOkMask) //Ack Byte is not included in the resp buf
+void RWDModule::command(uint8_t cmd, const uint8_t* params, int paramsLen, uint8_t* resp, size_t respLen, uint8_t ackOk, size_t ackOkMask) //Ack Byte is not included in the resp buf
 {
-  if(!ready())
+  if(!ready()) //If reader is not ready, does not submit another command yet
     return;
+  
+  //Setup command
   m_cmd = cmd;
-  m_paramsBuf = (byte*) params;
+  
+  //Setup parameters
+  m_paramsBuf = (uint8_t*) params;
   m_paramsLen = paramsLen;
+  
+  //Setup response
   m_respBuf = resp;
   m_respLen = respLen;
+  
+  //Pos in buf is 0
   m_pos = 0;
+  
+  //Setup ack requirements
   m_ackOk = ackOk;
   m_ackOkMask = ackOkMask;
+  
   m_state = CMD_QUEUED;
 }
   
 bool RWDModule::ready()
 {
-#if 0
-  static int lastState;
-  if(m_state != lastState)
-  {
-    printf("State %d\n", m_state);
-    lastState = m_state;
-    if(m_state==RECEIVING_ACK)
-      printf("Ack %02x\n", m_ack);
-  }
-#endif
   return (m_state==READY);
 }
    
-bool RWDModule::result(byte* pAck /*= NULL*/)
+bool RWDModule::result(uint8_t* pAck /*= NULL*/)
 {
-  if(!ready())
+  if(!ready()) //Has command returned yet?
     return false;
-  if(pAck)
+  if(pAck) //If pointer is passed, return reader's ack
     *pAck = m_ack;
-  return ((m_ack & m_ackOkMask) == m_ackOk);
+  return ((m_ack & m_ackOkMask) == m_ackOk); //Return whether the reader returned an error or OK ack
 }
 
 void RWDModule::intClearToSend()
 {
   //Start sending command when Clear To Send falls
-  if(m_state == CMD_QUEUED)
+  if(m_state == CMD_QUEUED) //Is there a command to be sent?
   {
     m_state = SENDING_CMD;
     intTx(); //Start sending command
@@ -69,15 +94,15 @@
     return;  
   if(m_pos==0) //Must send command-byte first
     m_serial.putc((char)m_cmd);
-  while(true)
+  while(true) //Send payload
   {
-    if(m_pos >= m_paramsLen)
+    if(m_pos >= m_paramsLen) //Payload sent completely?
     {
       m_pos = 0;
-      m_state = WAITING_FOR_ACK;
+      m_state = WAITING_FOR_ACK; //Next step
       return;
     }
-    m_serial.putc((char)m_paramsBuf[m_pos]);
+    m_serial.putc((char)m_paramsBuf[m_pos]); //Send payload byte
     m_pos++;
   }
 }
@@ -86,23 +111,23 @@
 {
   if(m_state == WAITING_FOR_ACK) //Get answer
   {
-    m_ack = m_serial.getc();
-    if( (m_ack & m_ackOkMask) != m_ackOk )
+    m_ack = m_serial.getc(); //Get Ack
+    if( (m_ack & m_ackOkMask) != m_ackOk ) //Check if an error is returned
     {
-      m_state = READY;
+      m_state = READY; //If yes, transfer is completed and result() will return false
       return;
     }
     if(m_respLen)
     {
-      m_state = RECEIVING_ACK;
+      m_state = RECEIVING_ACK; //Ack OK, now need to get response
     }
     else
     {
-      m_state = READY;
+      m_state = READY; //Ack OK, end of transfer
       return;
     }
   }
-  if(m_state != RECEIVING_ACK) //Error
+  if(m_state != RECEIVING_ACK) //Error, should not happen
   {
     while(m_serial.readable())
       m_serial.getc(); //Dump these bytes
@@ -110,12 +135,12 @@
   }
   while(m_serial.readable()) //Read payload
   {
-    m_respBuf[m_pos] = (byte) m_serial.getc();
+    m_respBuf[m_pos] = (uint8_t) m_serial.getc(); //Read byte and put it in resp buf
     m_pos++;
     if(m_pos >= m_respLen)
     {
       m_pos = 0;
-      m_state = READY;
+      m_state = READY; //End of transfer, response retrieved with success
     }
   }
 }

--- a/RWDModule.h	Tue Jul 13 10:37:26 2010 +0000
+++ b/RWDModule.h	Tue Jul 13 16:11:29 2010 +0000
@@ -1,22 +1,64 @@
+
+/*
+Copyright (c) 2010 Donatien Garnier (donatiengar [at] gmail [dot] com)
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
 
 #ifndef RWD_MODULE_H
 #define RWD_MODULE_H
 
 #include "mbed.h"
 
-typedef unsigned char byte;
-
+/*
+The RWD modules from IB Technology are RFID readers working with different frequencies and protocols but with a common instructions set and pinout.
+*/
 class RWDModule
 {
 public:
+  /*
+  Connect module using serial port pins tx, rx and DigitalIn pin cts (clear-to-send).
+  */
   RWDModule(PinName tx, PinName rx, PinName cts);
+  
+  /*
+  Destroys instance.
+  */
   virtual ~RWDModule();
   
-  void command(byte cmd, const byte* params, int paramsLen, byte* resp, int respLen, byte ackOk, byte ackOkMask); //Ack Byte is not included in the resp buf
+
+  /*
+  Executes the command cmd on the reader, with parameters set in params buffer of paramsLen length. The acknowledge byte sent back by the reader masked with ackOkMask  must be equal to ackOk for the command to be considered a success. If so, the result is stored in buffer resp of length respLen.
+  This is a non-blocking function, and ready() should be called to check completion.
+  Please note that the buffers references must remain valid until the command has been executed.
+  */
+  void command(uint8_t cmd, const uint8_t* params, int paramsLen, uint8_t* resp, size_t respLen, uint8_t ackOk, size_t ackOkMask); //Ack Byte is not included in the resp buf
   
+  /*
+  Returns true if the previous command has been executed and an other command is ready to be sent.
+  */
   bool ready(); //Ready for a command / response is available
   
-  bool result(byte* pAck = NULL); //Get wether last command was succesful, and complete ack byte if a ptr is provided
+  /*
+  Returns true if the previous command was successful. If pAck is provided, the actual acknowledge byte returned by the reader is stored in that variable.
+  */
+  bool result(uint8_t* pAck = NULL); //Get wether last command was succesful, and complete ack byte if a ptr is provided
 
 private:
   void intClearToSend(); //Called on interrupt when CTS line falls
@@ -26,17 +68,17 @@
   Serial m_serial;
   InterruptIn m_cts;  
   
-  byte m_cmd;
-  byte* m_paramsBuf;
-  byte* m_respBuf;
-  int m_pos;
-  int m_paramsLen;
-  int m_respLen;
+  uint8_t m_cmd;
+  uint8_t* m_paramsBuf;
+  uint8_t* m_respBuf;
+  size_t m_pos;
+  size_t m_paramsLen;
+  size_t m_respLen;
     
-  byte m_ackOk;
-  byte m_ackOkMask;
+  uint8_t m_ackOk;
+  uint8_t m_ackOkMask;
   
-  byte m_ack;
+  uint8_t m_ack;
   
   enum
   {