Diff: CANPort.h

Revision:

0:7b81b19d9b10

Child:

1:f0b4e47d948d

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CANPort.h	Sun Jul 15 15:15:19 2012 +0000
@@ -0,0 +1,285 @@
+/// @file CANPort.h is where all the port level functionality is defined
+///
+/// This module creates the physical interface, services the hardware, and provides
+/// additional functionality on top of that (e.g. timestamp messages).
+///
+/// @todo Instead of providing a callback directly to the user code, all 
+///       callbacks should be handled in this class, and then the user 
+///       callback could be activated. In this way, the rxCounter, timestamps,
+///       and other features are preserved.
+///
+/// @note Copyright &copr; 2011 by Smartware Computing, all rights reserved.
+///     Individuals may use this application for evaluation or non-commercial
+///     purposes. Within this restriction, changes may be made to this application
+///     as long as this copyright notice is retained. The user shall make
+///     clear that their work is a derived work, and not the original.
+///     Users of this application and sources accept this application "as is" and
+///     shall hold harmless Smartware Computing, for any undesired results while
+///     using this application - whether real or imagined.
+///
+/// @author David Smart, Smartware Computing
+///
+/// History
+/// v1.01 20110608
+/// \li initial version numbered to match other CAN components
+///
+#ifndef CANPORT_H
+#define CANPORT_H
+#include "mbed.h"
+#include "CANMessage.h"
+#include "Utilities.h"      // mbed <-> Visual Studio
+
+
+typedef enum {
+    HIGHSPEED,
+    NORMALSPEED,
+    STANDBY
+} CANSlopeControl_T;
+
+typedef enum {
+    MONITOR,
+    ACTIVE
+} CANBusMode_T;
+
+/// This is the CANPort, which is the physical interface to CAN
+///
+/// This derived class has a number of additional capabilities:
+/// \li activity indicator to show receive and transmit activity per port
+/// \li slope control pin to permit controlling performance and power modes
+/// \li counters, to keep track of received and transmitted messages
+/// \li and more...
+///
+class CANPort {
+public:
+
+    /// The advanced form of the constructure to create a CANPort, name 
+    /// an activity indicator, and name a slope control pin
+    ///
+    /// This version lets you specify the receive and transmit pins
+    /// for a CANPort, indicate a pin which is used to indicate
+    /// CAN activity, both receive and transmit, and identify a slope
+    /// control pin.
+    ///
+    /// @param chNum is the user assigned channel number given to this port
+    /// @param rd is the receive pin
+    /// @param td is the transmit pin
+    /// @param activityPin is the PWM pin used to indicate CAN traffic
+    /// @param slopePin is the DigitalInOut pin used to control slope
+    /// @param slope is the initial slope setting
+    ///
+    CANPort(CANCHANNEL_T chNum, PinName rd, PinName td, PinName activityPin = NC, PinName slopePin = NC, CANSlopeControl_T slope = NORMALSPEED);
+    
+    /// Destroys the CANPort
+    virtual ~CANPort();
+
+    /// Transmit a message to the bus
+    ///
+    /// This method transmits a message to the bus.
+    ///
+    /// @param msg is a CANmsg
+    /// @returns true if the message was successfully written to CAN
+    ///
+    bool TransmitMsg(CANmsg msg);
+    
+    /// Read a message from the bus into a buffer
+    ///
+    /// This method will extract a message from the bus and put it 
+    /// in the message space provided
+    ///
+    /// @param msg is a reference to a CANmsg into which the msg is placed
+    /// @returns true if a message was received and processed
+    ///
+    bool ReceiveMsg(CANmsg &msg);
+    
+    /// This flashes the activity indicator associated with this CANPort
+    ///
+    /// If the activity indicator is configured.
+    ///
+    /// @param tx indiciates if the flash is to be a sign of xmt or rcv
+    ///        it will flash dimly for a transmit and bright for a receive
+    ///
+    void Flash(CANDIR_T tx);
+    
+    /// This extinguishes the activity indicator associated with this CANPort
+    ///
+    /// If the activity indicator is configured.
+    ///
+    void Extinguish(void);
+    
+    /// Attach a callback whenever a CAN receive interrupt is generated
+    ///
+    /// This attaches a simple callback to the CAN ISR
+    ///
+    /// @param fptr pointer to the function to be called 
+    ///
+    void Attach( void  (*fptr)(void) );
+    
+    /// Attach a callback whenever a CAN receive interrupt is generated
+    ///
+    /// This attaches a callback to the CAN ISR
+    ///
+    /// @param tptr pointer to the object to call the member function on 
+    /// @param mptr pointer to the member function to be called 
+    ///
+    template <typename T> void Attach(T * tptr, void (T::*mptr)(void)) {
+        can->attach(tptr, mptr);
+    }
+    
+    /// This provides control of the AutoReset feature
+    ///
+    /// AutoReset is a feature that permits automatically resetting the 
+    /// CAN chip when it is trapped in an error state (e.g. bus off).
+    /// The default is disabled.
+    ///
+    /// @param enable is used to enable or disable the auto reset feature
+    /// @returns true if the command was accepted
+    ///
+    bool SetAutoReset(bool enable);
+    
+    /// This returns the current state of the AutoReset feature
+    ///
+    /// Returns a value indicating the current state
+    ///
+    /// @returns true if AutoReset is enabled
+    /// @returns false if AutoReset is disabled
+    ///
+    bool GetAutoReset() { return autoReset; }
+    
+    /// This provides control to set the bus mode as active or listener only
+    ///
+    /// The CAN adapter can be placed into a monitor(LISTENER) mode (sometimes
+    /// called promiscuous mode) or into an active mode, in which case it
+    /// will send hardware acknowledge.
+    ///
+    /// @param mode is either MONITOR or ACTIVE
+    /// @returns true if the command was accepted
+    ///
+    bool SetBusMode(CANBusMode_T mode);
+    
+    /// This returns the current state of the bus mode
+    ///
+    /// @returns MONITOR if the chip is in the monitor (listen / promiscuous) mode
+    /// @returns ACTIVE if the chip is in the active mode
+    ///
+    CANBusMode_T GetBusMode();
+
+    /// This provides control to set the transceiver slope control mode
+    ///
+    /// Many CAN transceivers can be operated in one of several modes - 
+    /// \li HIGHSPEED - which supports the highest frequency of communication, but
+    ///     does tend to generate more EMI unless the cable is properly shielded
+    /// \li NORMALSPEED - which wave-shapes the rising and falling edge, and
+    ///     significantly reduces the EMI concerns, but may trade off the
+    ///     highest performance.
+    /// \li STANDBY - which puts the chip into the lowest power state, and prevents
+    ///     transmission of a message. It can typically still receive messages,
+    ///     but this mode may also be useful for other purposes (wake on CAN,
+    ///     autobaud w/o disrupting bus traffic, etc.)
+    ///
+    /// @param slope sets the slope control to one of the states HIGHSPEED, 
+    ///     NORMALSPEED, or STANDBY
+    /// @returns true if the command succeeded
+    /// @returns false if the command failed, which may be due to not having
+    ///     defined a slope control pin.
+    ///
+    bool SetSlopeControl(CANSlopeControl_T slope);
+    
+    /// This returns the current state of the slope control
+    /// 
+    /// The state is controlled by the SetSlopeControl command.
+    ///
+    /// @returns the current state; one of HIGHSPEED, NORMALSPEED, or STANDBY
+    ///
+    CANSlopeControl_T GetSlopeControl();
+
+    /// This sets the bitrate for the CAN channel
+    ///
+    /// This sets the bitrate for the CAN channel. The rate is in bits per
+    /// second. The actual bitrate and the sample point is automagically 
+    /// determined from the internal algorithms provided by the mbed library.
+    ///
+    /// This API appears redundant to the frequency api, however this one
+    /// will retain the rate setting and then permits the query of the bitrate.
+    /// 
+    /// @param rate is the desired bitrate in bits per second.
+    /// @returns true if teh command succeeded
+    ///
+    bool SetBitRate(int rate);
+    
+    /// This returns the current desired bitrate for the CAN channel
+    ///
+    /// This returns the previously set bitrate. Note that the actual bitrate
+    /// may be different, due to the internal calculations of the mbed library.
+    ///
+    /// @returns the bitrate in bits per second
+    ///
+    int GetBitRate();
+
+    /// This returns the number of messages that were sent by this CAN channel
+    ///
+    /// The counter is never reset.
+    ///
+    /// @returns the number of messages sent by this CAN channel
+    ///
+    int GetTxCounter();
+
+    /// This returns the number of messages that were received by this CAN channel
+    ///
+    /// The counter is never reset.
+    ///
+    /// @returns the number of messages received by this CAN channel
+    ///
+    int GetRxCounter();
+    
+    /// This returns the number of transmit errors
+    ///
+    /// As counted by the hardware
+    ///
+    /// @returns the number of transmit errors
+    int GetTxErrorCounter();
+    
+    /// This returns the number of receive errors
+    ///
+    /// As counted by the hardware
+    ///
+    /// @returns the number of receive errors
+    int GetRxErrorCounter();
+    
+    /// This resets the CAN interface
+    ///
+    /// Unconditionally.
+    ///
+    /// @returns true if success
+    ///
+    bool ResetChip();
+    
+    /// This writes various CAN info to the selected serial channel
+    ///
+    /// When supplied with a Serial port channel, this will output
+    /// some possibly interesting information about the CAN configuration.
+    /// It does not output details for only the active objects channel,
+    /// rather it outputs information about the CAN subsystem.
+    ///
+    /// @param stream is the handle of a serial channel
+    /// @returns nothing
+    ///
+    void PrintInfo(Serial * stream);
+
+private:
+    CANCHANNEL_T channel;       // user assigned port number of this port
+    CAN * can;                  // bind to a specific CAN
+    CANBusMode_T busMode;       // monitor or active mode
+    int bitRate;                // bit rate for this bus
+    PwmOut * activityPin;       // LED to indicate activity
+    Timeout activityTimeout;    // used to extinguish the LED
+
+    DigitalInOut * slopePin;    // pin used to control the transceiver slope modes
+    PinName slopePinName;
+    CANSlopeControl_T slopeMode;// current mode
+
+    bool autoReset;             // true when auto reset on error is enabled
+    uint32_t txCounter;
+    uint32_t rxCounter;
+};
+
+#endif // CANPORT_H