CANPort.h

00001 /// @file CANPort.h is where all the port level functionality is defined
00002 ///
00003 /// This module creates the physical interface, services the hardware, and provides
00004 /// additional functionality on top of that (e.g. timestamp messages).
00005 ///
00006 /// @todo Instead of providing a callback directly to the user code, all 
00007 ///       callbacks should be handled in this class, and then the user 
00008 ///       callback could be activated. In this way, the rxCounter, timestamps,
00009 ///       and other features are preserved.
00010 ///
00011 /// @note Copyright &copr; 2011 by Smartware Computing, all rights reserved.
00012 ///     Individuals may use this application for evaluation or non-commercial
00013 ///     purposes. Within this restriction, changes may be made to this application
00014 ///     as long as this copyright notice is retained. The user shall make
00015 ///     clear that their work is a derived work, and not the original.
00016 ///     Users of this application and sources accept this application "as is" and
00017 ///     shall hold harmless Smartware Computing, for any undesired results while
00018 ///     using this application - whether real or imagined.
00019 ///
00020 /// @author David Smart, Smartware Computing
00021 ///
00022 /// History
00023 /// v1.01 20110608
00024 /// \li initial version numbered to match other CAN components
00025 ///
00026 #ifndef CANPORT_H
00027 #define CANPORT_H
00028 #include "mbed.h"
00029 #include "CANMessage.h"
00030 
00031 /// This is the CANPort, which is the physical interface to CAN
00032 ///
00033 /// This derived class has a number of additional capabilities:
00034 /// \li activity indicator to show receive and transmit activity per port
00035 /// \li slope control pin to permit controlling performance and power modes
00036 /// \li counters, to keep track of received and transmitted messages
00037 /// \li and more...
00038 ///
00039 class CANPort : public CAN {
00040 public:
00041 
00042     typedef enum {
00043         HIGHSPEED,
00044         NORMALSPEED,
00045         STANDBY
00046     } CANSlopeControl_T;
00047     
00048     typedef enum {
00049         MONITOR,
00050         ACTIVE
00051     } CANBusMode_T;
00052 
00053     /// The advanced form of the constructure to create a CANPort, name 
00054     /// an activity indicator, and name a slope control pin
00055     ///
00056     /// This version lets you specify the receive and transmit pins
00057     /// for a CANPort, indicate a pin which is used to indicate
00058     /// CAN activity, both receive and transmit, and identify a slope
00059     /// control pin.
00060     ///
00061     /// @param chNum is the user assigned channel number given to this port
00062     /// @param rd is the receive pin
00063     /// @param td is the transmit pin
00064     /// @param activityPin is the PWM pin used to indicate CAN traffic
00065     /// @param slopePin is the DigitalInOut pin used to control slope
00066     /// @param slope is the initial slope setting
00067     ///
00068     CANPort(CANCHANNEL_T chNum, PinName rd, PinName td, PinName activityPin = NC, PinName slopePin = NC, CANSlopeControl_T slope = NORMALSPEED);
00069     
00070     /// Destroys the CANPort
00071     virtual ~CANPort();
00072 
00073     /// Transmit a message to the bus
00074     ///
00075     /// This method transmits a message to the bus.
00076     ///
00077     /// @param msg is a CANmsg
00078     /// @returns true if the message was successfully written to CAN
00079     ///
00080     bool TransmitMsg(CANmsg msg);
00081     
00082     /// Read a message from the bus into a buffer
00083     ///
00084     /// This method will extract a message from the bus and put it 
00085     /// in the message space provided
00086     ///
00087     /// @param msg is a reference to a CANmsg into which the msg is placed
00088     /// @returns true if a message was received and processed
00089     ///
00090     bool ReceiveMsg(CANmsg &msg);
00091     
00092     /// This flashes the activity indicator associated with this CANPort
00093     ///
00094     /// If the activity indicator is configured.
00095     ///
00096     /// @param tx indiciates if the flash is to be a sign of xmt or rcv
00097     ///        it will flash dimly for a transmit and bright for a receive
00098     ///
00099     void Flash(CANDIR_T tx);
00100     
00101     /// This extinguishes the activity indicator associated with this CANPort
00102     ///
00103     /// If the activity indicator is configured.
00104     ///
00105     void Extinguish(void);
00106     
00107     /// Attach a callback whenever a CAN receive interrupt is generated
00108     ///
00109     /// This attaches a simple callback to the CAN ISR
00110     ///
00111     /// @param fptr pointer to the function to be called 
00112     ///
00113     void Attach( void  (*fptr)(void) );
00114     
00115     /// Attach a callback whenever a CAN receive interrupt is generated
00116     ///
00117     /// This attaches a callback to the CAN ISR
00118     ///
00119     /// @param tptr pointer to the object to call the member function on 
00120     /// @param mptr pointer to the member function to be called 
00121     ///
00122     //template <typename T> void Attach(T * tptr, void (T::*mptr)(void)) {
00123     //    can->attach(callback(tptr, mptr));
00124     //}
00125     
00126     /// This provides control of the AutoReset feature
00127     ///
00128     /// AutoReset is a feature that permits automatically resetting the 
00129     /// CAN chip when it is trapped in an error state (e.g. bus off).
00130     /// The default is disabled.
00131     ///
00132     /// @param enable is used to enable or disable the auto reset feature
00133     /// @returns true if the command was accepted
00134     ///
00135     bool SetAutoReset(bool enable);
00136     
00137     /// This returns the current state of the AutoReset feature
00138     ///
00139     /// Returns a value indicating the current state
00140     ///
00141     /// @returns true if AutoReset is enabled
00142     /// @returns false if AutoReset is disabled
00143     ///
00144     bool GetAutoReset() { return autoReset; }
00145     
00146     /// This provides control to set the bus mode as active or listener only
00147     ///
00148     /// The CAN adapter can be placed into a monitor(LISTENER) mode (sometimes
00149     /// called promiscuous mode) or into an active mode, in which case it
00150     /// will send hardware acknowledge.
00151     ///
00152     /// @param mode is either MONITOR or ACTIVE
00153     /// @returns true if the command was accepted
00154     ///
00155     bool SetBusMode(CANBusMode_T mode);
00156     
00157     /// This returns the current state of the bus mode
00158     ///
00159     /// @returns MONITOR if the chip is in the monitor (listen / promiscuous) mode
00160     /// @returns ACTIVE if the chip is in the active mode
00161     ///
00162     CANBusMode_T GetBusMode();
00163 
00164     /// This provides control to set the transceiver slope control mode
00165     ///
00166     /// Many CAN transceivers can be operated in one of several modes - 
00167     /// \li HIGHSPEED - which supports the highest frequency of communication, but
00168     ///     does tend to generate more EMI unless the cable is properly shielded
00169     /// \li NORMALSPEED - which wave-shapes the rising and falling edge, and
00170     ///     significantly reduces the EMI concerns, but may trade off the
00171     ///     highest performance.
00172     /// \li STANDBY - which puts the chip into the lowest power state, and prevents
00173     ///     transmission of a message. It can typically still receive messages,
00174     ///     but this mode may also be useful for other purposes (wake on CAN,
00175     ///     autobaud w/o disrupting bus traffic, etc.)
00176     ///
00177     /// @param slope sets the slope control to one of the states HIGHSPEED, 
00178     ///     NORMALSPEED, or STANDBY
00179     /// @returns true if the command succeeded
00180     /// @returns false if the command failed, which may be due to not having
00181     ///     defined a slope control pin.
00182     ///
00183     bool SetSlopeControl(CANSlopeControl_T slope);
00184     
00185     /// This returns the current state of the slope control
00186     /// 
00187     /// The state is controlled by the SetSlopeControl command.
00188     ///
00189     /// @returns the current state; one of HIGHSPEED, NORMALSPEED, or STANDBY
00190     ///
00191     CANSlopeControl_T GetSlopeControl();
00192 
00193     /// This sets the bitrate for the CAN channel
00194     ///
00195     /// This sets the bitrate for the CAN channel. The rate is in bits per
00196     /// second. The actual bitrate and the sample point is automagically 
00197     /// determined from the internal algorithms provided by the mbed library.
00198     ///
00199     /// This API appears redundant to the frequency api, however this one
00200     /// will retain the rate setting and then permits the query of the bitrate.
00201     /// 
00202     /// @param rate is the desired bitrate in bits per second.
00203     /// @returns true if the command succeeded
00204     ///
00205     bool SetBitRate(uint32_t rate);
00206     
00207     /// This returns the current desired bitrate for the CAN channel
00208     ///
00209     /// This returns the previously set bitrate. Note that the actual bitrate
00210     /// may be different, due to the internal calculations of the mbed library.
00211     ///
00212     /// @returns the bitrate in bits per second
00213     ///
00214     uint32_t GetBitRate();
00215 
00216     /// This returns the number of messages that were sent by this CAN channel
00217     ///
00218     /// The counter is never reset.
00219     ///
00220     /// @returns the number of messages sent by this CAN channel
00221     ///
00222     int GetTxCounter();
00223 
00224     /// This returns the number of messages that were received by this CAN channel
00225     ///
00226     /// The counter is never reset.
00227     ///
00228     /// @returns the number of messages received by this CAN channel
00229     ///
00230     int GetRxCounter();
00231     
00232     /// This returns the number of transmit errors
00233     ///
00234     /// As counted by the hardware
00235     ///
00236     /// @returns the number of transmit errors
00237     int GetTxErrorCounter();
00238     
00239     /// This returns the number of receive errors
00240     ///
00241     /// As counted by the hardware
00242     ///
00243     /// @returns the number of receive errors
00244     int GetRxErrorCounter();
00245     
00246     /// This resets the CAN interface
00247     ///
00248     /// Unconditionally.
00249     ///
00250     /// @returns true if success
00251     ///
00252     bool ResetChip();
00253     
00254     /// This writes various CAN info to the selected serial channel
00255     ///
00256     /// When supplied with a Serial port channel, this will output
00257     /// some possibly interesting information about the CAN configuration.
00258     /// It does not output details for only the active objects channel,
00259     /// rather it outputs information about the CAN subsystem.
00260     ///
00261     /// @param stream is the handle of a serial channel
00262     /// @returns nothing
00263     ///
00264     void PrintInfo(Serial * stream);
00265 
00266 private:
00267     CANCHANNEL_T channel;       // user assigned port number of this port
00268     //CAN * can;                  // bind to a specific CAN
00269     CANBusMode_T busMode;       // monitor or active mode
00270     int bitRate;                // bit rate for this bus
00271     PwmOut * activityPin;       // LED to indicate activity
00272     Timeout activityTimeout;    // used to extinguish the LED
00273 
00274     DigitalInOut * slopePin;    // pin used to control the transceiver slope modes
00275     PinName slopePinName;
00276     CANSlopeControl_T slopeMode;// current mode
00277 
00278     bool autoReset;             // true when auto reset on error is enabled
00279     uint32_t txCounter;
00280     uint32_t rxCounter;
00281 };
00282 
00283 #endif // CANPORT_H