Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

LOW_linkDS2490.h

Go to the documentation of this file.
00001 /***************************************************************************
00002                           LOW_linkDS2490.h  -  description
00003                              -------------------
00004     begin                : Sun Oct 12 2003
00005     copyright            : (C) 2003 by Harald Roelle
00006     email                : roelle@informatik.uni-muenchen.de
00007  ***************************************************************************/
00008 
00009 /***************************************************************************
00010  *                                                                         *
00011  *   This program is free software; you can redistribute it and/or modify  *
00012  *   it under the terms of the GNU General Public License as published by  *
00013  *   the Free Software Foundation; either version 2 of the License, or     *
00014  *   (at your option) any later version.                                   *
00015  *                                                                         *
00016  ***************************************************************************/
00017 
00018 #ifndef LOW_LINKDS2490_H
00019 #define LOW_LINKDS2490_H
00020 
00021 
00022 #include "LOW_link.h"
00023 #include "LOW_linkFlexibleSpeed.h"
00024 #include "LOW_portUsb_Factory.h"
00025 
00026 
00027 /** Link class for DS2490 USB to 1-Wire Bridge Chip.
00028 
00029     DS2490 features:
00030 
00031       - Communicates at regular and overdrive 1- Wire® speeds
00032       - Supports 12V EPROM programming and stiff 5V pullup for EEPROM, sensors, and crypto iButton
00033       - Slew rate controlled 1-Wire timing and active pullup to accommodate long
00034         1-Wire network lines and reduce radiation
00035       - Programmable 1-Wire timing and driver characteristics accommodate a wide range of 1-Wire
00036         network configurations
00037       - Low- to high-level command types, including macros, for generating 1-Wire communication
00038       - Crystal oscillator timebase provides precision timed 1-Wire waveforms
00039       - High-speed 12Mbps Universal Serial Bus (USB) interface
00040       - Integrated USB-compliant transceiver
00041       - Supports USB remote wake-up from a 1-Wire device event to resume a suspended host system
00042       - 0oC to +70oC operating temperature range
00043 
00044     The DS2490 is a bridge chip that enables communication between a USB host system and a 1-Wire bus.
00045     It provides regular, overdrive, and flexible 1-Wire communication speeds and a full-speed 12Mbps
00046     connection to USB. USB vendor-specific commands defined in this specification are used to control
00047     the DS2490 and communicate with attached 1-Wire devices.
00048 
00049     This class is thread-safe.
00050     
00051     @todo Provide assignment operator and copy constructor
00052     @todo Finish documentation
00053 
00054     @author  Harald Roelle
00055     @author  Parts of the documentation by Dallas Semiconductors / Maxim Integrated Products
00056  */
00057 class LOW_linkDS2490 : public LOW_link, public LOW_linkFlexibleSpeed {
00058 
00059 //=======================================================================================
00060 public:
00061 
00062   //=====================================================================================
00063   //
00064   // constructors
00065   //
00066 
00067   /** Constructor.
00068 
00069       Timings for flexible speed is configured to the recommeded optimal parameters
00070       as of app note #148.
00071 
00072       @param  inUsbDevSpec        USB device specifier of the DS2490.
00073       @param  inHasExternalPower  Whether the attached bus supplies external power.
00074       @param  inAllowProgPulse    Whether the program pulse should be allowed.
00075    */
00076   LOW_linkDS2490( const LOW_portUsb_Factory::usbDeviceSpecifier_t inUsbDevSpec,
00077                   const bool inHasExternalPower, const bool inAllowProgPulse = false);
00078 
00079                   
00080   /** Constructor.
00081       Automatically finds the first DS2490 on USB bus(es) and uses it.
00082 
00083       Timings for flexible speed is configured to the recommeded optimal parameters
00084       as of app note #148.
00085 
00086       @param  inHasExternalPower  Whether the attached bus supplies external power.
00087       @param  inAllowProgPulse    Whether the program pulse should be allowed.
00088    */
00089   LOW_linkDS2490( const bool inHasExternalPower, const bool inAllowProgPulse = false);
00090 
00091   
00092   /** Destructor.
00093    */
00094   virtual ~LOW_linkDS2490();
00095 
00096 
00097   //=====================================================================================
00098   //
00099   // Standard methods required by LOW_link
00100   //
00101 
00102   virtual std::string getLinkFamily() const { return "DS2490 USB link"; };
00103 
00104   //! @name Bus touch (write/read) methods required by LOW_link
00105   //!@{
00106   virtual bool touchBit( const bool inSendBit, const strongPullup_t inPullup = pullUp_NONE);
00107   virtual uint8_t touchByte( const uint8_t inSendByte, const strongPullup_t inPullup = pullUp_NONE);
00108   virtual byteVec_t touchBlock( const byteVec_t &inBytes, const strongPullup_t inPullup = pullUp_NONE);
00109   //!@}
00110 
00111   //! @name Higher level methods required by LOW_link
00112   //!@{
00113   virtual LOW_deviceID::deviceIDVec_t searchDevices( const bool inOnlyAlarm, const LOW_deviceIDRaw inPreload,
00114                                                      const LOW_deviceIDRaw::devFamCode_t inFamCode, const bool inDoReset);
00115   //!@}
00116 
00117   //! @name Misc methods required by LOW_link
00118   //!@{
00119   virtual void resetLinkAdapter();
00120   virtual bool resetBus();
00121   virtual void strongPullup( const unsigned long inMicroSecs);
00122   virtual void strongPullup( const strongPullup_t inPullupTime);
00123   virtual void programPulse( const unsigned long inMicroSecs);
00124   virtual void programPulse( const progPulse_t inPulseTime);
00125   //!@}
00126 
00127 
00128   //=====================================================================================
00129   //
00130   // Standard methods required by LOW_linkFlexibleSpeed
00131   //
00132 
00133   //! @name Methods required by LOW_linkFlexibleSpeed
00134   //!@{
00135   virtual void setWireSpeed( const wireSpeed_t inWireSpeed);
00136   virtual wireSpeed_t getWireSpeed();
00137   virtual void setPullDownSlewRate( const pdSlewRate_t inPDSR);
00138   virtual pdSlewRate_t getPullDownSlewRate();
00139   virtual void setWrite1LowTime( const w1LowTime_t inW1LT);
00140   virtual w1LowTime_t getWrite1LowTime();
00141   virtual void setSampleOffsetWrite0Rec( const soW0RecTime_t inSOW0RT);
00142   virtual soW0RecTime_t getSampleOffsetWrite0Rec();
00143   //!@}
00144 
00145 
00146 
00147 //=======================================================================================
00148 protected:
00149 
00150 
00151   //=====================================================================================
00152   //
00153   // Standard methods required by LOW_link
00154   //
00155 
00156   virtual void doSearchSequence( const LOW_deviceIDRaw &inBranchVector,
00157                                  LOW_deviceIDRaw &outFoundID, LOW_deviceIDRaw &outDiscrVec);
00158 
00159                                  
00160                                  
00161 //=======================================================================================
00162 private:
00163 
00164   //=====================================================================================
00165   //
00166   // constants
00167   //
00168 
00169   //! @name USB related constants.
00170   //!@{
00171   static const LOW_portUsbDevice::usbVendorID_t   usbVendorID  = 0x04fa;        /**< Dallas/Maxim USB vendor ID. */
00172   static const LOW_portUsbDevice::usbProductID_t  usbProductID = 0x2490;        /**< Dallas/Maxim USB DS2490 product ID. */
00173   static const LOW_portUsbDevice::usbInterface_t  usbDefaultInterface = 0;      /**< Default and only USB interface of DS2490. */
00174   static const LOW_portUsbDevice::bmRequestType_t vendorCmd_requestType = 0x40; /**< Request type of DS2490 vendor specific commands. */
00175   //!@}
00176 
00177 
00178   //! @name USB timeout constants.
00179   //!@{
00180   static const LOW_portUsbDevice::usbTimeout_t   ctlCmd_usbTimeout  = 1000; /**< Timeout in ms for control commands. */
00181   static const LOW_portUsbDevice::usbTimeout_t   modCmd_usbTimeout  = 1000; /**< Timeout in ms for mode commands. */
00182   static const LOW_portUsbDevice::usbTimeout_t   comCmd_usbTimeout  = 1000; /**< Timeout in ms for communicaton commands. */
00183   //!@}
00184 
00185 
00186   //! @name USB interface alternate settings.
00187   //!@{
00188   static const LOW_portUsbDevice::usbSetting_t usbAltSetting_10_16 = 0; /**< poll interval EP2/EP3 = 10ms; max packet size = 16 bytes;
00189                                                                              Long interrupt polling interval, small packet size for bulk pipes. */
00190   static const LOW_portUsbDevice::usbSetting_t usbAltSetting_10_64 = 1; /**< poll interval EP2/EP3 = 10ms; max packet size = 64 bytes;
00191                                                                              Long interrupt polling interval, large packet size for bulk pipes. */
00192   static const LOW_portUsbDevice::usbSetting_t usbAltSetting_1_16  = 2; /**< poll interval EP2/EP3 =  1ms; max packet size = 16 bytes;
00193                                                                              Short interrupt polling interval, small packet size for bulk pipes. */
00194   static const LOW_portUsbDevice::usbSetting_t usbAltSetting_1_64  = 3; /**< poll interval EP2/EP3 =  1ms; max packet size = 64 bytes;
00195                                                                              Short interrupt polling interval, large packet size for bulk pipes. */
00196   //!@}
00197 
00198   
00199   //! @name USB endpoints.
00200   //!@{
00201   /** Endpoint for the bi-directional default control pipe. It is used for the USB enumeration process,
00202       USB core request communication, and all DS2490 specific command communication.
00203    */ 
00204   static const LOW_portUsbDevice::usbEndpoint_t usbControlEP  = 0;
00205   /** Endpoint for an interrupt pipe (device to host) and is used to relay DS2490 status register data and
00206       specific command execution completion and/or error information to the host. It is also used to inform
00207       the host of 1-Wire device-attach detection. The polling period requested for EP1 depends on the
00208       alternate interface setting of the 1-Wire interface.
00209    */
00210   static const LOW_portUsbDevice::usbEndpoint_t usbStatusInEP = 1;
00211   /** Endpoint for a bulk data out pipe (data from host) and is used to transmit 1-Wire device data from the
00212       host to the DS2490. The information received at this endpoint will be transmitted as data on the 1-Wire bus.
00213    */
00214   static const LOW_portUsbDevice::usbEndpoint_t usbDataOutEP  = 2;
00215   /** FIFO size in bytes of endpoint usbDataOutEP.
00216    */
00217   static const unsigned int usbDataOutEP_FIFOsize             = 128;
00218   /** Endpoint for a bulk data in pipe (data to host) and is used to send data received by the DS2490 from
00219       the 1-Wire bus back to the host for processing.
00220    */
00221   static const LOW_portUsbDevice::usbEndpoint_t usbDataInEP   = 3;
00222   /** FIFO size in bytes of endpoint usbDataOutEP.
00223    */
00224   static const unsigned int usbDataInEP_FIFOsize              = 128;
00225   //!@}
00226 
00227 
00228   /** @name Command types.
00229       Three different vendor-specific command types exist to control and communicate with the DS2490:
00230       
00231         - Control commands are used to manage various device functions including the processing of
00232           communication commands, buffer clearing, and SW reset.
00233 
00234         - Communication commands are used for 1-Wire data and command I/O.
00235 
00236         - Mode commands are used to establish the 1-Wire operational characteristics of the DS2490
00237           such as slew rate, low time, strong pullup, etc.
00238 
00239       Control, Communication and Mode commands, like USB core requests, are communicated over the
00240       default control pipe at EP0.
00241    */
00242   //!@{
00243   static const LOW_portUsbDevice::bRequest_t control_cmdType = 0x00; //**< 1-Wire interface control commands. */
00244   static const LOW_portUsbDevice::bRequest_t comm_cmdType    = 0x01; //**< 1-Wire interface communication commands. */
00245   static const LOW_portUsbDevice::bRequest_t mode_cmdType    = 0x02; //**< 1-Wire interface operational mode commands. */
00246   //!@}
00247 
00248   
00249   //! @name Control commands.
00250   //!@{
00251   static const LOW_portUsbDevice::wValue_t resetDevice_ctlCmd    = 0x0000;  /**< Control command. */
00252   static const LOW_portUsbDevice::wValue_t startExe_ctlCmd       = 0x0001;  /**< Control command. */
00253   static const LOW_portUsbDevice::wValue_t resumeExe_ctlCmd      = 0x0002;  /**< Control command. */
00254   static const LOW_portUsbDevice::wValue_t haltExeIdle_ctlCmd    = 0x0003;  /**< Control command. */
00255   static const LOW_portUsbDevice::wValue_t haltExeDone_ctlCmd    = 0x0004;  /**< Control command. */
00256   static const LOW_portUsbDevice::wValue_t flushCommCmds_ctlCmd  = 0x0007;  /**< Control command. */
00257   static const LOW_portUsbDevice::wValue_t flushRcvBuffer_ctlCmd = 0x0008;  /**< Control command. */
00258   static const LOW_portUsbDevice::wValue_t flushXmtBuffer_ctlCmd = 0x0009;  /**< Control command. */
00259   static const LOW_portUsbDevice::wValue_t getCommCmds_ctlCmd    = 0x000A;  /**< Control command. */
00260   //!@}
00261 
00262   //! @name Mode commands.
00263   //!@{
00264   static const LOW_portUsbDevice::wValue_t pulseEn_modCmd            = 0x0000;  /**< Mode command. */
00265   static const LOW_portUsbDevice::wValue_t speedChangeEn_modCmd      = 0x0001;  /**< Mode command. */
00266   static const LOW_portUsbDevice::wValue_t oneWireSpeed_modCmd       = 0x0002;  /**< Mode command. */
00267   static const LOW_portUsbDevice::wValue_t strongPuDuration_modCmd   = 0x0003;  /**< Mode command. */
00268   static const LOW_portUsbDevice::wValue_t pulldownSlewRate_modCmd   = 0x0004;  /**< Mode command. */
00269   static const LOW_portUsbDevice::wValue_t progPulseDuration_modCmd  = 0x0005;  /**< Mode command. */
00270   static const LOW_portUsbDevice::wValue_t write1LowTime_modCmd      = 0x0006;  /**< Mode command. */
00271   static const LOW_portUsbDevice::wValue_t dsow0Trec_modCmd          = 0x0007;  /**< Mode command. */
00272   //!@}
00273 
00274   //! @name Base for communication commands.
00275   //!@{
00276   static const LOW_portUsbDevice::wValue_t setDuration_comCmdBase         = 0x0012;  /**< Communication command. */
00277   static const LOW_portUsbDevice::wValue_t pulse_comCmdBase               = 0x0030;  /**< Communication command. */
00278   static const LOW_portUsbDevice::wValue_t oneWireReset_comCmdBase        = 0x0042;  /**< Communication command. */
00279   static const LOW_portUsbDevice::wValue_t bitIO_comCmdBase               = 0x0020;  /**< Communication command. */
00280   static const LOW_portUsbDevice::wValue_t byteIO_comCmdBase              = 0x0052;  /**< Communication command. */
00281   static const LOW_portUsbDevice::wValue_t blockIO_comCmdBase             = 0x0074;  /**< Communication command. */
00282   static const LOW_portUsbDevice::wValue_t matchAccess_comCmdBase         = 0x0064;  /**< Communication command. */
00283   static const LOW_portUsbDevice::wValue_t readStraight_comCmdBase        = 0x0080;  /**< Communication command. */
00284   static const LOW_portUsbDevice::wValue_t doAndRelease_comCmdBase        = 0x6092;  /**< Communication command. */
00285   static const LOW_portUsbDevice::wValue_t setPath_comCmdBase             = 0x00a2;  /**< Communication command. */
00286   static const LOW_portUsbDevice::wValue_t writeSramPage_comCmdBase       = 0x00b2;  /**< Communication command. */
00287   static const LOW_portUsbDevice::wValue_t writeEprom_comCmdBase          = 0x00c4;  /**< Communication command. */
00288   static const LOW_portUsbDevice::wValue_t readCrcProtPage_comCmdBase     = 0x00d4;  /**< Communication command. */
00289   static const LOW_portUsbDevice::wValue_t readRedirectPageCrc_comCmdBase = 0x21e4;  /**< Communication command. */
00290   static const LOW_portUsbDevice::wValue_t searchAccess_comCmdBase        = 0x00f4;  /**< Communication command. */
00291   //!@}
00292 
00293   
00294   //! @name Communication command bitmasks.
00295   //!@{
00296 
00297   /** RTS = 1 returns the discrepancy information to the host if SM = 1 and there are more devices than could
00298               be discovered in the current pass.
00299       RTS = 0 does not return discrepancy information.
00300    */
00301   static const LOW_portUsbDevice::wValue_t RTS_bitmask   = 0x4000;
00302 
00303   /** CIB = 1 prevents a strong pullup to 5V if SPU = 1 and the bit read back from the 1- Wire bus is 1.
00304       CIB = 0 generally enables the strong pullup to 5V.
00305    */
00306   static const LOW_portUsbDevice::wValue_t CIB_bitmask   = 0x4000;
00307 
00308   /** PST = 1 continuously generate 1-Wire Reset sequences until a presence pulse is discovered.
00309       PST = 0 generate only one 1-Wire Reset sequence.
00310    */
00311   static const LOW_portUsbDevice::wValue_t PST_bitmask   = 0x4000;
00312 
00313   /** PS = 1 reduces the preamble size to 2 bytes (rather than 3).
00314       PS = 0 sets preamble size to 3 bytes.
00315    */
00316   static const LOW_portUsbDevice::wValue_t PS_bitmask    = 0x4000;
00317 
00318   /** DT = 1 activates/selects the CRC16 generator.
00319       DT = 0 specifies no CRC.
00320    */
00321   static const LOW_portUsbDevice::wValue_t DT_bitmask    = 0x2000;
00322 
00323   /** SPU = 1 inserts a strong pullup to 5V after a Bit or Byte or Block I/O or Do & Release command.
00324       SPU = 0 no strong pullup.
00325    */
00326   static const LOW_portUsbDevice::wValue_t SPU_bitmask   = 0x1000;
00327 
00328   /** F = 1 clears the buffers in case an error occurred during the execution of the previous command;
00329             requires that ICP = 0 in the previous command.
00330       F = 0 prevents the buffers from being cleared.
00331    */
00332   static const LOW_portUsbDevice::wValue_t F_bitmask     = 0x0800;
00333 
00334   /** NTF = 1 always generate communication command processing result feedback if ICP = 0
00335       NTF = 0 generate communication command processing result feedback only if an error occurs
00336               and ICP = 0. If ICP = 1 command result feedback is suppressed for either case,
00337               see the ICP bit above.
00338    */
00339   static const LOW_portUsbDevice::wValue_t NTF_bitmask   = 0x0400;
00340 
00341   /** ICP = 1 indicates that the command is not the last one of a macro; as a consequence command processing
00342               result feedback messages are suppressed.
00343       ICP = 0 indicates that the command is the last one of a macro or single command operation;
00344               enables command processing result feedback signaling.
00345    */
00346   static const LOW_portUsbDevice::wValue_t ICP_bitmask   = 0x0200;
00347 
00348   /** RST = 1 inserts a 1-Wire Reset before executing the command.
00349       RST = 0 no 1-Wire Reset inserted.
00350    */
00351   static const LOW_portUsbDevice::wValue_t RST_bitmask   = 0x0100;
00352 
00353   /** SE = 1 enable the speed change on the 1-Wire bus.
00354       SE = 0 disable the speed change on the 1-Wire bus.
00355    */
00356   static const LOW_portUsbDevice::wValue_t SE_bitmask    = 0x0008; 
00357 
00358   /** R = 1 performs a read function.
00359       R = 0 performs a write function.
00360    */
00361   static const LOW_portUsbDevice::wValue_t R_bitmask     = 0x0008;
00362 
00363   /** Z = 1 checks if the 0-bits in the byte to be written are 0-bits in the byte read back form the device.
00364       Z = 0 checks if the byte to be written is identical to the one read back from the device.
00365    */
00366   static const LOW_portUsbDevice::wValue_t Z_bitmask     = 0x0008;
00367 
00368   /** SM = 1 searches for and reports ROM Ids without really accessing a particular device.
00369       SM = 0 makes a  Strong Access  to a particular device.
00370    */
00371   static const LOW_portUsbDevice::wValue_t SM_bitmask    = 0x0008;
00372 
00373   /** CH = 1 follows the chain if the page is redirected.
00374       CH = 0 stops reading if the page is redirected.
00375    */
00376   static const LOW_portUsbDevice::wValue_t CH_bitmask    = 0x0008;
00377 
00378   /** D       Data bit value to be written to the 1-Wire bus.
00379    */
00380   static const LOW_portUsbDevice::wValue_t D_bitmask     = 0x0008;
00381 
00382   /** TYPE = 1 specifies programming pulse duration.
00383       TYPE = 0 specifies strong pullup duration.
00384    */
00385   static const LOW_portUsbDevice::wValue_t TYPE_bitmask  = 0x0008;
00386 
00387   /** IM = 1 enables immediate execution of the command. Assumes that all 1-Wire device data required by the
00388              command has been received at EP2.
00389       IM = 0 prevents immediate execution of the command; execution must be started through a
00390              control function command.
00391    */
00392   static const LOW_portUsbDevice::wValue_t IM_bitmask    = 0x0001;
00393   //!@}
00394 
00395   
00396   //! @name State register enable bitmasks.
00397   //!@{
00398   /** SPUE If set to 1, the strong pullup to 5V is enabled, if set to 0, it is disabled.
00399    */
00400   static const uint8_t SPUE_bitmask = 0x01;
00401   /** PRGE If set to 1, a 12V programming pulse is enabled, if set to 0, it is disabled.
00402    */
00403   static const uint8_t PRGE_bitmask = 0x02;
00404   /** SPCE If set to 1, a dynamic 1-Wire bus speed change through a Communication
00405            command is enabled, if set to 0, it is disabled.
00406    */
00407   static const uint8_t SPCE_bitmask = 0x04;
00408   //!@}
00409 
00410   
00411   //! @name State register device status bitmasks.
00412   //!@{
00413   /** SPUA if set to 1, the strong pullup to 5V is currently active, if set to 0, it is inactive.
00414    */
00415   static const uint8_t SPUA_bitmask = 0x01;
00416   /** PRGA if set to 1, a 12V programming pulse is currently being generated, if set to 0, it is not.
00417    */
00418   static const uint8_t PRGA_bitmask = 0x02;
00419   /** 12VP if set to 1, the external 12V programming voltage is present, if set to 0, it is not present.
00420    */
00421   static const uint8_t VP12_bitmask = 0x04;
00422   /** PMOD if set to 1, the DS2490 is powered from USB and external sources,
00423            if set to 0, all DS2490 power is provided from USB.
00424    */
00425   static const uint8_t PMOD_bitmask = 0x08;
00426   /** HALT if set to 1, the DS2490 is currently halted, if set to 0, the device is not halted.
00427    */
00428   static const uint8_t HALT_bitmask = 0x10;
00429   /** IDLE if set to 1, the DS2490 is currently idle, if set to 0, the device is not idle.
00430    */
00431   static const uint8_t IDLE_bitmask = 0x20;
00432   /** EPOF  Endpoint 0 FIFO status, see Note 1.
00433    */
00434   static const uint8_t EP0F_bitmask = 0x80;
00435   //!@}
00436 
00437   
00438   //! @name Communication command error bitmasks.
00439   //!@{
00440 
00441   /** 1-Wire Device Detect Byte
00442    */
00443   static const uint8_t devDetect_code = 0xa5;
00444 
00445   /** EOS A value of 1 indicates that a SEARCH ACCESS with SM = 1 ended sooner than expected
00446           reporting less ROM ID s than specified in the  number of devices  parameter.
00447    */
00448   static const uint8_t EOS_bitmask = 0x80;
00449 
00450   /** RDP A value of 1 indicates that a READ REDIRECT PAGE WITH/CRC encountered a page that is redirected.
00451    */
00452   static const uint8_t RDP_bitmask = 0x40;
00453 
00454   /** CRC A value of 1 indicates that a CRC error occurred when executing one of the following
00455          commands: WRITE SRAM PAGE, WRITE EPROM, READ CRC PROT PAGE, or READ REDIRECT PAGE W/CRC.
00456    */
00457   static const uint8_t CRC_bitmask = 0x20;
00458 
00459   /** CMP A value of 1 indicates an error with one of the following: Error when reading the confirmation
00460           byte with a SET PATH command. The WRITE EPROM command did not program successfully. There was
00461           a difference between the byte written and then read back with a BYTE I/O command
00462    */
00463   static const uint8_t CMP_bitmask = 0x10;
00464 
00465   /** VPP A value of 1 indicates that during a PULSE with TYPE = 1 or WRITE EPROM command the 12V
00466           programming pulse was not seen on the 1-Wire bus; this could indicate that there were other
00467           devices on the bus that clamped the voltage to a value lower than VPP or that the programming
00468           pulse was disabled with a mode command.
00469    */
00470   static const uint8_t VPP_bitmask = 0x08;
00471 
00472   /** APP A value of 1 indicates that a 1-WIRE RESET revealed an Alarming Presence Pulse.
00473    */
00474   static const uint8_t APP_bitmask = 0x04;
00475 
00476   /** SH  A value of 1 indicates that a 1-WIRE RESET revealed a short to the 1-Wire bus or the
00477           SET PATH command could not successfully connect a branch due to a short.
00478    */
00479   static const uint8_t SH_bitmask  = 0x02;
00480 
00481   /** NRS A value of 1 indicates an error with one of the following: 1-WIRE RESET did not reveal
00482           a Presence Pulse. SET PATH command did not get a Presence Pulse from the branch that was
00483           to be connected. No response from one or more ROM ID bits during a SEARCH ACCESS command.
00484    */
00485   static const uint8_t NRS_bitmask = 0x01;
00486 
00487   //!@}
00488 
00489   
00490   //=====================================================================================
00491   //
00492   // type definitions
00493   //
00494     
00495   //! @name DS2490 specific configuration values.
00496   //!@{
00497   /** Type for wirespeed */
00498   typedef enum { /** 16 kbps */ normal_OWSPEED=0x00, flexible_OWSPEED, /** 142 kbps */ overdrive_OWSPEED } OWSPEED_val_t;
00499   /** Type for flexible speed pulldown slew rate in V/microsec */
00500   typedef enum { PDSR_15=0x00,    PDSR_2_2,  PDSR_1_65, PDSR_1_37, PDSR_1_1, PDSR_0_83, PDSR_0_7, PDSR_0_55} PDSR_val_t;
00501   /** Type for flexible speed write-1 low time in microsec */
00502   typedef enum { W1LT_8=0x00,     W1LT_9,    W1LT_10,   W1LT_11,   W1LT_12,  W1LT_13,   W1LT_14,  W1LT_15}   W1LT_val_t;
00503   /** Type for flexible speed DSO/ W0R time in microsec */
00504   typedef enum { SOW0RT_3=0x00,   SOW0RT_4,  SOW0RT_5,  SOW0RT_6,  SOW0RT_7, SOW0RT_8,  SOW0RT_9, SOW0RT_10} SOW0RT_val_t;
00505   //!@}
00506 
00507   /** Type to define result handling with communication commands. */
00508   typedef enum {
00509     noResult_rsltHdl=0x00,    /**< NTF=x  ICP=1, Never generate result register feedback. */
00510     resultOnError_rsltHdl,    /**< NTF=0  ICP=0, Generate result register on error and leave in EP1 FIFO. */
00511     resultAlways_rsltHdl      /**< NTF=1  ICP=0, Always generate result register and leave in EP1 FIFO. */
00512   }  resultHandling_t;
00513 
00514   
00515   //! @name Status and result code types.
00516   //!@{
00517 
00518   /** Status information, raw format from device */
00519   typedef struct deviceFeedbackRaw_t {
00520     uint8_t  enableFlags;
00521     uint8_t  oneWireSpeed;
00522     uint8_t  strongPullupDuration;
00523     uint8_t  progPulseDuration;
00524     uint8_t  pulldownSlewRate;
00525     uint8_t  write1LowTime;
00526     uint8_t  dsow0RecTime;
00527     uint8_t  reserved0;
00528     uint8_t  deviceStatusFlags;
00529     uint8_t  commCmdLO;
00530     uint8_t  commCmdHI;
00531     uint8_t  commCmdBufferStatus;
00532     uint8_t  dataOutBufferStatus;
00533     uint8_t  dataInBufferStatus;
00534     uint8_t  reserved1;
00535     uint8_t  reserved2;
00536     uint8_t  resultCode[16];
00537   } deviceFeedbackRaw_t;
00538 
00539   
00540   /** Status information, decoded format */
00541   typedef struct resultCode_t {
00542     bool deviceDetected;             /**< 1-wire device detect byte found */
00543     bool searchAccessDeviceUnderrun; /**< EOS bit */
00544     bool pageIsRedirected;           /**< RDP bit */
00545     bool crcError;                   /**< CRC bit */
00546     bool compareError;               /**< CMP bit */
00547     bool progVoltageMissingOnBus;    /**< VPP bit */
00548     bool alarmingPresencePulse;      /**< APP bit */
00549     bool shortToGround;              /**< SH bit  */
00550     bool noPresencePulse;            /**< NRS bit */
00551   } resultCode_t;
00552 
00553   typedef std::vector<resultCode_t>   resultCodeVec_t;  /**< Vector type of resultCode_t. */
00554 
00555   /** Status information, decoded format */
00556   typedef struct deviceFeedback_t {
00557     bool           isStrongPullupEnabled;       /**< SPUE bit */
00558     bool           isProgPulseEnabled;          /**< PRGE bit */
00559     bool           isDynSpeedChangeEnabled;     /**< SPCE bit */
00560     OWSPEED_val_t  oneWireSpeed;                /**< current 1-Wire bus speed code */
00561     uint8_t        strongPullupDurationFactor;  /**< current pullup duration */
00562     uint8_t        progPulseDurationFactor;     /**< current programming pulse duration */
00563     PDSR_val_t     pulldownSlewRate;            /**< current pulldown slew rate code */
00564     W1LT_val_t     write1LowTime;               /**< current Write-1 low time code */
00565     SOW0RT_val_t   dsow0RecTime;                /**< current data sample offset/ Write-0 recovery time code */
00566     bool           strongPullupCurrentActive;   /**< SPUA bit */
00567     bool           progPulseCurrentActive;      /**< PRGA bit */
00568     bool           progVoltagePresent;          /**< 12VP bit */
00569     bool           deviceExternalPowered;       /**< PMOD bit */
00570     bool           deviceHalted;                /**< HALT bit */
00571     bool           deviceIdle;                  /**< IDLE bit */
00572     bool           ep0FifoOverflowError;        /**< EPOF bit */
00573     uint16_t       currentCommCmd;              /**< Communication command currently being processed. If the device is idle, a register value of 0x00 is sent. */
00574     uint8_t        commCmdBufferUsage;          /**< Number of data bytes currently contained in the 16-byte FIFO used to hold communication commands. */
00575     uint8_t        dataOutBufferUsage;          /**< Number of data bytes currently contained in the 128-byte FIFO used to write data to the 1-Wire bus. */
00576     uint8_t        dataInBufferUsage;           /**< Number of data bytes currently contained in the 128-byte command FIFO used to read data from the 1-Wire bus. */
00577     uint8_t        resultCount;                 /**< Number of results received. */
00578     resultCode_t   compoundResults;             /**< All results ORed together. */
00579   } deviceFeedback_t;
00580 
00581   //!@}
00582 
00583   
00584 
00585   //=====================================================================================
00586   //
00587   // attributes
00588   //
00589 
00590   LOW_portUsbDevice *usbDevice;  /**< The USB device we use. */
00591 
00592 
00593 
00594   //=====================================================================================
00595   //
00596   // methods
00597   //
00598 
00599   /** @name Mid-layer methods.
00600    */
00601   //!@{
00602 
00603   /** Actions common to all constructors.
00604    */
00605   void commonConstructorActions();
00606   
00607   
00608   /** Fetch device status and all available result codes.
00609       @param outDevFeedback    Device status read from the device.
00610       @param outResultCodeVec  All result codes which were available.
00611    */
00612   void readDeviceStatus( deviceFeedback_t &outDevFeedback, resultCodeVec_t &outResultCodeVec);
00613 
00614   
00615   /** Periodically poll the device status until the it's status is idle.
00616       @param outDeviceFeedback  Feedback status of the last poll.
00617       @param outResultCodeVec   All result codes being available during polling.
00618       @param inTimeout          Maximum time to wait for the device to become idle.
00619    */
00620   void waitUntilIdle( deviceFeedback_t &outDeviceFeedback, resultCodeVec_t &outResultCodeVec, 
00621                       const LOW_portUsbDevice::usbTimeout_t inTimeout);
00622 
00623   /** Universal and internal funtion for single strong pullups.
00624       @param inPullupFactor  Factor of pulse length. Length will be factor times 16ms.
00625    */
00626   void strongPullupInternal( const unsigned int inPullupFactor);
00627 
00628   /** Universal and internal funtion for program pulses.
00629       @param inPullupFactor  Factor of pulse length. Length will be factor times 8us.
00630    */
00631   void progPulseInternal( const unsigned int inPulseFactor);
00632   
00633   //!@}
00634 
00635 
00636   
00637   /** @name Control command methods.
00638       Control commands are used to control the processing of Communication commands/data and can also be used
00639       to issue a device Reset. There are 9 Control commands. Like Mode commands, Control commands are
00640       immediately processed by the DS2490 when they are received.
00641    */
00642   //!@{
00643 
00644   /** Performs a hardware reset equivalent to the power-on reset.
00645       This includes clearing all endpoint buffers and loading the Mode control registers
00646       with their default values.
00647    */
00648   virtual void ctlCmd_resetDevice();
00649 
00650   /** Starts execution of Communication commands.
00651       This command is also required to start the execution of Communication commands with an
00652       IM (immediate execution control) bit set to logic 0.
00653    */
00654   virtual void ctlCmd_startExecution();
00655 
00656 
00657   /** Used to resume execution of a Communication command that was halted with either of
00658       the HALT EXECUTION commands.
00659    */
00660   virtual void ctlCmd_resumeExecution();
00661 
00662 
00663   /** Used to halt the execution of the current Communication command after the 1-Wire bus
00664       has returned to the idle state.
00665       Further Communication command processing is stopped until a RESUME EXECUTION command is received.
00666       This command, or the HALT EXECUTION WHEN DONE command, is also used to terminate a strong pullup
00667       or programming pulse of semi-infinite or infinite duration.
00668    */
00669   virtual void ctlCmd_haltExecutionWhenIdle();
00670 
00671 
00672   /** Used to halt the execution of a Communication command after the current command execution
00673       is complete.
00674       Further Communication command processing is stopped until a RESUME EXECUTION command is received.
00675       This command, or the HALT EXECUTION WHEN IDLE command, is also used to terminate a strong pullup
00676       or programming pulse of semi-infinite or infinite duration.
00677    */
00678   virtual void ctlCmd_haltExecutionWhenDone();
00679 
00680 
00681   /** Used to clear all unexecuted Communication commands from the command FIFO.
00682       The DS2490 must be in a halted state before the FLUSH COMM CMDS command can be processed.
00683    */
00684   virtual void ctlCmd_flushCommCmds();
00685 
00686 
00687   /** Used to clear EP3 receive data FIFO (data from 1- Wire device).
00688       The DS2490 must be in a halted state before the FLUSH DATA RCV BUFFER command can be processed.
00689    */
00690   virtual void ctlCmd_flushDataRcvBuffer();
00691 
00692 
00693   /** Used to clear EP2 transmit data FIFO (data to 1- Wire device).
00694       The DS2490 must be in a halted state before the FLUSH DATA XMT BUFFER command can be processed.
00695    */
00696   virtual void ctlCmd_flushDataXmtBuffer();
00697 
00698 
00699   /** Used to retrieve unexecuted Communication commands and parameters from the command FIFO.
00700 
00701       The DS2490 must be in a halted state before the GET COMM CMDS command can be processed.
00702 
00703       Unexecuted commands are returned over EP0 in the control transfer data phase.
00704       Host software is responsible for determining the number of command/parameter bytes to be returned and
00705       specifying the value in the wLength field of the control transfer setup packet.
00706 
00707       Commands/parameters are deleted from the FIFO as they are transmitted to the host; the command
00708       pointer used with the FIFO is updated as values are read. Any commands/parameters that are not
00709       transferred remain in the FIFO and will be processed when command execution resumes.
00710 
00711       If the wLength value passed is larger than the number of command/parameter bytes, the DS2490 will
00712       terminate the control transfer with a short data packet.
00713    */
00714   virtual void ctlCmd_getCommCmds( byteVec_t &outBytes);
00715   
00716   //!@}
00717 
00718 
00719   
00720   /** @name Mode command methods.
00721       1-Wire characteristics and features (speed, durations, slew rate, etc.) are controlled with discrete 
00722       Mode commands and/or embedded Communication command parameters. Parameter values and enable/disable 
00723       settings are used for characteristic control. Mode settings are stored in the DS2490 State Registers 
00724       and can be read at any time or at the polling interval of EP1. Enable/disable settings are used to 
00725       control three global features:   
00726       
00727         - Strong pullup to +5V   
00728         
00729         - +12V EPROM programming pulse   
00730         
00731         - Dynamic 1-Wire bus communication speed change through a communication command 
00732         
00733       The settings for these three global controls are accessible only through Mode commands; the features 
00734       are either enabled or disabled with the appropriate Mode command. Specific Communication commands 
00735       exist to issue a strong pullup, a programming pulse, or speed change. When the corresponding setting 
00736       is enabled the feature is usable as part of a communication command when disabled the feature is not usable. 
00737       Parameter values and codes are used to specify and control 1-Wire bus characteristics:   
00738       
00739         - 1-Wire bus communication speed   
00740         
00741         - +5V strong pullup duration   
00742         
00743         - +12V programming pulse duration   
00744         
00745         - Pulldown slew rate   
00746         
00747         - Write-1 low time   
00748         
00749         - Data sample offset/Write-0 Recovery time
00750 
00751       These six settings are controllable with discrete Mode commands or as embedded command/parameter values 
00752       in Communications commands. Mode commands are immediately processed by the DS2490 when they are received. 
00753    */
00754   //!@{
00755   /** Used to enable or disable a 1-Wire strong pullup pulse to 5V and/or +12V EPROM programming pulse.
00756       Two bit positions in the parameter byte are used to control the enabled/disabled state for each pulse type. 
00757       The specific pulse is enabled when the respective bit is set to a 1 and disabled when set to a 0. 
00758       The DS2490 power-up default state for both strong pullup and programming pulse is disabled. 
00759    */
00760   virtual void modCmd_setEnablePulse( const bool inEnableStrongPullup, const bool inEnableProgPulse);
00761   
00762   
00763   /** Used to enable or disable a 1-Wire communication speed change. 
00764       Enabled when a TRUE parameter value is passed with the command, disabled with a FALSE. 
00765       The DS2490 power-up default state for speed change is disabled. 
00766    */
00767   virtual void modCmd_setEnableSpeedChange( const bool inEnableSpeedChange);
00768   
00769   
00770   /** Used to set the speed of 1-Wire communication; three settings are possible. 
00771       The DS2490 power-up default communication speed is regular.
00772    */
00773   virtual void modCmd_setOneWireSpeed( const OWSPEED_val_t inWireSpeed);
00774 
00775   
00776   /** Used to set the time duration of a 1-Wire strong pullup. 
00777       The time is controlled with an unsigned 8-bit binary number between 0x00 and 0xFE which specifies 
00778       the duration in multiples of 16ms. A value of 0x01 specifies 16ms, 0x02 equals 32ms, etc. 
00779       A value of 0x00 specifies infinite duration. Parameter value 0xFF is reserved and will cause 
00780       the device to deliver a pullup duration of <1µs. 
00781       To terminate an infinite duration pullup use either the HALT EXECUTION WHEN DONE or 
00782       HALT EXECUTION WHEN IDLE Control commands as described in Appendix 1. 
00783       The DS2490 power-up default strong pullup duration register value is 512ms.
00784    */
00785   virtual void modCmd_setStrongPullupDuration( const uint8_t inSpuDurationFactor);
00786 
00787   
00788   /** Used to set the time duration of a 1-Wire Programming Pulse. 
00789       The time is controlled with a an unsigned 8-bit binary number between 0x00 and 0xFE specifying 
00790       the duration in multiples of 8µs. A value of 0x00 stands for infinite duration. Parameter value 0xFF 
00791       is reserved and will cause the device to deliver a pulse duration of <1µs. To terminate an infinite 
00792       duration programming pulse use the HALT EXECUTION WHEN DONE or HALT EXECUTION WHEN IDLE command.
00793       The DS2490 power-up default strong pullup duration register value is 512µS.
00794    */
00795   virtual void modCmd_setProgPulseDuration( const uint8_t inPpDurationFactor);
00796 
00797   
00798   /** Used to select the pulldown slew rate for 1-Wire bus Flexible Speed operation. 
00799       Eight pulldown slew rates are possible. The nominal pulldown slew rate for Regular speed is 0.83V/s and 
00800       for Overdrive speeds it is 15V/s.
00801       The DS2490 pulldown slew rate power-up default value for Flexible speed is 0.83V/  s.
00802    */
00803   virtual void modCmd_setPulldownSlewRate( const PDSR_val_t inPDSR);
00804   
00805   
00806   /** Used to select the Write-1 low time for 1-Wire bus Flexible speed operation.
00807       Eight Write-1 low time durations are possible. The nominal Write-1 Low Time for Regular speed is 8us, at 
00808       Overdrive speed it is 1us. 
00809       The DS2490 Write-1 Low Time power-up default value for Flexible speed is 12us.
00810    */
00811   virtual void modCmd_setWrite1LowTime( const W1LT_val_t inW1LT);
00812   
00813   
00814   /** Used to select the Data Sample Offset (tDSO) / Write-0 recovery (tW0R) time (DSO/W0R) for 1-Wire 
00815       bus Flexible Speed operation. 
00816       Eight DSO/W0R times are possible. The nominal DSO/W0R time for Regular speed is 3us, for Overdrive 
00817       speed the Data Sample Offset is 1us and the Write-0 Recovery Time is 3 s. 
00818       The DS2490 DSO/W0R power-up default value for Flexible speed is 7us.
00819    */
00820   virtual void modCmd_setDsoW0RecoveryTime( const SOW0RT_val_t inSOW0RT);
00821   
00822   //!@}
00823 
00824   
00825   
00826   /** @name Communication command methods.
00827   
00828       Communication commands are used to communicate with and control an attached 1-Wire device(s). 
00829       Communication commands also contain embedded command bits for conditional control or additional 
00830       functionality. 
00831       
00832       Unlike Mode and Control commands, Communication command processing is controlled by host software 
00833       by setting embedded command bits within a Communication command. For example, a command macro form 
00834       is supported in which several Communication commands and parameter data are sent/buffered in the 
00835       DS2490 and then processed as a group. 
00836       
00837       Embedded command bit ICP is used to create macro command sets. Also, unlike Mode and Control commands, 
00838       several forms of Communication command monitoring exist for host software to track processing progress. 
00839       Depending on the settings of embedded communication command bits ICP and NTF, a Result Register value 
00840       may be generated to provide command processing feedback. 
00841       
00842       Communication command buffer (FIFO) status and 1-Wire data transmit/received buffers (EP2/3 FIFOs) 
00843       status can also be monitored via the State Registers.
00844    */
00845   //!@{
00846   
00847   /** Changes the State Register pulse duration value for either the +12V programming pulse or strong pullup.
00848       The new duration value is loaded into the duration register specified. The duration values can alternatively
00849       be changed using a Mode command. The new duration setting remains effective until changed by another 
00850       SET DURATION or MODE Command. See section  MODE COMMANDS  for duration parameter value setting.
00851    */
00852   virtual void comCmd_setDuration( const uint8_t inTimeFactor,
00853                                    const bool inSpecifyProgPulse,
00854                                    const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00855                                    const bool inImmediateExec = true);
00856   
00857   
00858   /** Used to temporarily pull the 1-Wire bus to +12V in order to program an EPROM device or 
00859       to generate a strong pullup to 5V in order to provide extra power for an attached iButton device, 
00860       e.g., temperature sensor or crypto iButton. 
00861       
00862       The pulse duration is determined by the value in the respective mode register, programming pulse or 
00863       strong pullup. The 12VP bit in the Device Status Flags (bit2) is used to determine whether +12V VPP 
00864       programming voltage is present.
00865    */
00866   virtual void comCmd_pulse( const bool inSpecifyProgPulse,
00867                              const bool inFlushBuffersOnErr,
00868                              const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00869                              const bool inImmediateExec = true);
00870 
00871   
00872   /** Used to generate a reset pulse on the 1-Wire bus and to optionally change the 1-Wire speed. 
00873       The new speed will take effect only if the embedded command bit SE is set to 1. When the 1-WIRE RESET is 
00874       sent after an Overdrive Skip ROM command, SE must be 1 and the new speed must be 0x02. 
00875       See MODE CONTROL section for additional communication speed information. To switch back to regular speed, 
00876       set SE = 1 and the new speed parameter to 0x00 (regular) or 0x01 (flexible).
00877    */
00878   virtual void comCmd_oneWireReset( const bool inLoopUntilPresenceDetect,
00879                                     const bool inEnableSpeedChange,
00880                                     const OWSPEED_val_t inSpeedSelector,
00881                                     const bool inFlushBuffersOnErr,
00882                                     const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00883                                     const bool inImmediateExec = true);
00884 
00885   
00886   /** Generates a single time slot on the 1-Wire bus and reads back the response. 
00887       This time slot may optionally be followed by a strong pullup using embedded command bits SPU and CIB. 
00888       With CIB = 1, a requested strong pullup will only occur if the read-back revealed a 0. 
00889       Data is returned to the host only if the embedded command bit ICP = 0. If ICP = 0, the bit read from 
00890       the 1-Wire device is stored in the EP3 FIFO and is read by the host using an EP3 bulk transaction.
00891    */
00892   virtual void comCmd_bitIO( const bool inWriteBit,
00893                              const bool inDoStrongPullup,
00894                              const bool inSuppressPullupOnRead1,
00895                              const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00896                              const bool inImmediateExec = true);
00897 
00898   
00899   /** Accomplishes a direct 1-Wire write and read with optional strong pullup after the last bit of the byte. 
00900       The optional strong pullup is controlled using embedded command bit SPU. For a write sequence, the data 
00901       byte to be written is included in the command setup packet as shown in Appendix 2.
00902       For a read sequence, the setup packet data byte value is set to 0xFF. 
00903       Data is returned to the host only if the embedded command bit ICP = 0. If ICP = 0, the byte read from 
00904       the 1-Wire device is stored in the EP3 FIFO and is read by the host using an EP3 bulk transaction.
00905    */
00906   virtual void comCmd_byteIO( const uint8_t inWriteByte,
00907                               const bool inDoStrongPullup,
00908                               const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00909                               const bool inImmediateExec = true);
00910 
00911   
00912   /** Accomplishes a direct 1-Wire write or read with optional strong pullup after the last byte of the block. 
00913       The optional strong pullup is controlled using embedded command bit SPU. Embedded command bit RST enables 
00914       a 1-Wire reset before the command executes. To accomplish a READ function all input data should be 0xFF, 
00915       otherwise the data read from the 1-Wire bus will be masked. For a block write sequence the EP2 FIFO must 
00916       be pre-filled with data before command execution. Additionally, for block sizes greater then the FIFO 
00917       size, the FIFO content status must be monitored by host SW so that additional data can be sent to the 
00918       FIFO when necessary. A similar EP3 FIFO content monitoring requirement exists for block read sequences. 
00919       During a block read the number of bytes loaded into the EP3 FIFO must be monitored so that the data can 
00920       be read before the FIFO overflows.
00921    */
00922   virtual void comCmd_blockIO( const uint16_t inWriteSize,
00923                                const bool inBusResetBefore,
00924                                const bool inDoStrongPullup,
00925                                const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00926                                const bool inImmediateExec = true);
00927 
00928   
00929   /** Is used to address a device on the active section of the 1-Wire bus using the Match ROM or Overdrive Match 
00930       command code. 
00931       The EP2 FIFO must be pre-filled with the 8 bytes target ROM ID before command execution. Embedded command 
00932       bit RST enables a 1-Wire reset before the command executes, and embedded command bit SE enables a 1-Wire 
00933       speed change that takes effect before the command executes.
00934    */
00935   virtual void comCmd_matchAccess( const uint8_t inMatchCommand,
00936                                    const bool inBusResetBefore,
00937                                    const bool inEnableSpeedChange,
00938                                    const OWSPEED_val_t inSpeedSelector,
00939                                    const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00940                                    const bool inImmediateExec = true);
00941 
00942   
00943   /** Transmits a user-specified preamble of data to the 1-Wire bus and then reads back as 
00944       many bytes as specified. 
00945       The preamble typically consists of a 1-Wire command code followed by TA1 and TA2. It is possible to include 
00946       a Match ROM command and ROM ID in the preamble to also address a device at the current speed. 
00947       This command can also be used to copy the scratchpad or disconnect a path. Embedded command bit RST enables 
00948       a 1-Wire reset before the command executes. The EP2 FIFO must be pre-filled with preamble data before 
00949       command execution. Additionally, for preamble sizes greater then the FIFO size, the FIFO content status 
00950       must be monitored by host SW so that additional data can be sent to the FIFO when necessary. A similar 
00951       EP3 FIFO content monitoring requirement exists for the block read. During a block read, the number of bytes 
00952       loaded into the EP3 FIFO must be monitored so that the data can be read before the FIFO overflows.
00953    */
00954   virtual void comCmd_readStraight( const uint8_t inWritePreambleSize,
00955                                     const uint16_t inReadSize,
00956                                     const bool inBusResetBefore,
00957                                     const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00958                                     const bool inImmediateExec = true);
00959 
00960   
00961   /** Typically used to control the activity of the CPU of the crypto iButton, which requires a release sequence. 
00962       This command can also be used to read from or write to the I/O buffer or Status Register of the crypto 
00963       iButton. A short preamble (3 bytes) consists of a 1-Wire command code followed by the release sequence. 
00964       A four-byte preamble with embedded command bit R = 1 consists of a 1-Wire command code followed by length 
00965       byte and the release sequence. A 4-byte preamble with embedded command bit R = 0 consists of a 1-Wire command 
00966       code followed by a status byte and the release sequence. The long preamble (minimum 5 bytes, embedded command 
00967       bit R = 0) consists of a 1-Wire command, a length byte, data bytes and the release sequence. In this case, 
00968       the length byte indicates the total number of bytes between the length byte and release sequence. The least 
00969       significant byte of the release sequence is transmitted first. Embedded command bit SPU must be 1 when trying 
00970       to run (start, continue) the CPU of the crypto iButton. In all other cases, SPU should be 0. Additionally, 
00971       embedded command bit F can be used to clear the communication command buffer and EP2/3 FIFOs if an error 
00972       occurs during execution of the command. The EP2 FIFO must be pre-filled with preamble data before command 
00973       execution. Additionally, for preamble sizes greater then the FIFO size, the FIFO content status must be 
00974       monitored by host SW so that additional data can be sent to the FIFO when necessary. A similar EP3 FIFO 
00975       content monitoring requirement exists for the block read. During a block read the number of bytes loaded 
00976       into the EP3 FIFO must be monitored so that the data can be read before the FIFO overflows.
00977    */
00978   virtual void comCmd_doAndRelease( const uint8_t inWritePreambleSize,
00979                                     const bool inDoReadOperation,
00980                                     const bool inDoStrongPullup,
00981                                     const bool inFlushBuffersOnErr,
00982                                     const resultHandling_t inResultHandling = resultOnError_rsltHdl,
00983                                     const bool inImmediateExec = true);
00984 
00985   
00986   /** Used to activate a series of couplers that finally provide the access to the target 1-Wire device. 
00987       Embedded command bit RST enables a 1-Wire reset before the command executes. Additionally, embedded 
00988       command bit F can be used to clear the communication command buffer and EP2/3 FIFOs if an error occurs 
00989       during execution of the command. The EP2 FIFO must be pre-filled with coupler data before command execution. 
00990       Additionally, for coupler data sizes greater then the EP2 FIFO size, the FIFO content status must be 
00991       monitored by host SW so that additional data can be sent to the FIFO when necessary. Upon completion of 
00992       command execution, the EP3 FIFO is loaded with a 1-byte value that indicates the number of couplers 
00993       activated. An NRS error code is an indication that there was no presence pulse on the branch that was 
00994       to be connected.
00995    */
00996   virtual void comCmd_setPath( const uint8_t inPreloadPathSize,
00997                                const bool inBusResetBefore,
00998                                const bool inFlushBuffersOnErr,
00999                                const resultHandling_t inResultHandling = resultOnError_rsltHdl,
01000                                const bool inImmediateExec = true);
01001 
01002   
01003   /** Used to write data to the scratchpad of an SRAM device and optionally check the CRC. To copy the data 
01004       to its final memory location, it is required to send the READ STRAIGHT command with a  copy scratchpad  
01005       preamble and a 0 block size. Embedded command bit DT = 1 activates the CRC16 generator. This command is 
01006       also applicable to the Write IPR function of the Crypto iButton if embedded command bit CIB = 1. To write 
01007       a partial page the page size parameter and the target address need to be set accordingly. The EP2 FIFO must 
01008       be pre-filled with preamble and SRAM data before command execution. Additionally, for data page sizes 
01009       greater then the EP2 FIFO size, the FIFO content status must be monitored by host SW so that additional data 
01010       can be sent to the FIFO when necessary.
01011    */
01012   virtual void comCmd_writeSramPage( const uint8_t inWriteSize,
01013                                      const bool inShortPreambleSize,
01014                                      const bool inActivateCrc16,
01015                                      const bool inFlushBuffersOnErr,
01016                                      const resultHandling_t inResultHandling = resultOnError_rsltHdl,
01017                                      const bool inImmediateExec = true);
01018 
01019   
01020   /** Used to write data directly to the data or status memory of a 1-Wire EPROM device. 
01021       If embedded command bit DT = 1, the CRC16 generator is selected; if DT = 0, CRC8 is used. Embedded command 
01022       bit Z controls the method used for comparison of the data written to the 1-Wire device. Additionally, embedded 
01023       command bit F can be used to clear the Communication command buffer and EP2/3 FIFOs if an error occurs during 
01024       execution of the command. The EP2 FIFO must be pre-filled with preamble and EPROM data before command execution. 
01025       Additionally, for data block sizes greater then the EP2 FIFO size, the FIFO content status must be monitored by 
01026       host SW so that additional data can be sent to the FIFO when necessary.
01027    */
01028   virtual void comCmd_writeEprom( const uint16_t inWriteSize,
01029                                   const bool inActivateCrc16,
01030                                   const bool inCheck0BitsOnly,
01031                                   const bool inFlushBuffersOnErr,
01032                                   const resultHandling_t inResultHandling = resultOnError_rsltHdl,
01033                                   const bool inImmediateExec = true);
01034 
01035   
01036   /** Used to read one or multiple CRC-protected pages of EPROM devices and to read tamper-detect bytes and counter 
01037       value of Monetary iButtons. 
01038       If embedded command bit DT = 1, the CRC16 generator is selected; if DT = 0, CRC8 is used. Embedded command 
01039       bit CIB is used to specify either a 2- or 3-byte read preamble. Additionally, embedded command bit F can be 
01040       used to clear the Communication command buffer and EP2/3 FIFOs if an error occurs during execution of the 
01041       command. The command can also be used to read a single partial page up to the end of that page and reading the 
01042       PIOs of a DS2406. This command is also applicable to the Read IPR function of the crypto iButton if CIB = 1. 
01043       The EP2 FIFO must be pre-filled with preamble data before command execution. To prevent overflow, the EP3 FIFO 
01044       must be monitored (and read if necessary) during command execution if reading more data than the size of the 
01045       EP3 FIFO.
01046    */
01047   virtual void comCmd_readCrcProtPage( const uint8_t inPageCount,
01048                                        const uint8_t inPageSizeLog2,
01049                                        const bool inShortPreambleSize,
01050                                        const bool inActivateCrc16,
01051                                        const bool inFlushBuffersOnErr,
01052                                        const resultHandling_t inResultHandling = resultOnError_rsltHdl,
01053                                        const bool inImmediateExec = true);
01054 
01055   
01056   /** Used to read a single page of data and check the CRC. 
01057       If the page is not redirected, the host will receive the page number and all its data. If the page is 
01058       redirected and embedded command bit CH = 1 the device will follow the trail of redirections until a page is 
01059       found that is not redirected. When found, the host will receive the page number and all data of that 
01060       particular page. If CH = 0 and the first read attempt reveals a redirection the host will only receive the 
01061       number of the page the addressed page is redirected to. Reading starts at a page boundary. Additionally, 
01062       embedded command bit F can be used to clear the communication command buffer and EP2/3 FIFOs if an error occurs 
01063       during execution of the command. An NRS error code is an indication of an infinite loop. The EP2 FIFO must be
01064       pre-filled with ROM ID and command code data before command execution. To prevent overflow, the EP3 FIFO must 
01065       be monitored (and read if necessary) during command execution if reading more data than the size of the EP3 FIFO.
01066    */
01067   virtual void comCmd_readRedirectPageCrc( const uint8_t inPageNumber,
01068                                            const uint8_t inPageSize,
01069                                            const bool inFollowRedirect,
01070                                            const bool inFlushBuffersOnErr,
01071                                            const resultHandling_t inResultHandling = resultOnError_rsltHdl,
01072                                            const bool inImmediateExec = true);
01073   
01074   
01075   /** Is used to either access a device using the Search ROM command or to identify the devices on 
01076       the active segments of a 1-Wire Network. 
01077       Embedded command bit SM is used to specify the type of search. Embedded command bit RTS is used to control 
01078       discrepancy information reporting. Additionally, embedded command bit F can be used to clear the Communication 
01079       command buffer and EP2/3 FIFOs if an error occurs during execution of the command. An NRS error code indicates 
01080       that there was no response on at least one of the 64 bits of the ROM search. The EP2 FIFO must be pre-filled 
01081       with ROM ID data before command execution. To prevent overflow, the EP3 FIFO must be monitored (and read if 
01082       necessary) during command execution if returning more data than the size of the EP3 FIFO.
01083    */
01084   virtual void comCmd_searchAccess( const uint8_t inMaxDevNum,
01085                                     const uint8_t inSearchCommand,
01086                                     const bool inSearchWithoutFullAccess,
01087                                     const bool inReturnDiscrepancyInfo,
01088                                     const bool inBusResetBefore,
01089                                     const bool inFlushBuffersOnErr,
01090                                     const resultHandling_t inResultHandling = resultOnError_rsltHdl,
01091                                     const bool inImmediateExec = true);
01092 
01093                                     
01094   /** Handle common bits of all communication commands.
01095    */
01096   void handleCommonComCmdBits( LOW_portUsbDevice::wValue_t &inOutValueCmd,
01097                                const resultHandling_t inResultHandling, const bool inImmediateExec);
01098 
01099 
01100   //!@}
01101 
01102   
01103   
01104   //=====================================================================================
01105   //!
01106   //! @name Enumeration type conversion methods
01107   //!
01108   //@{
01109 
01110 
01111   /** Convert value of type PDSR_val_t to pdSlewRate_t.
01112       @throw  internal_error  Thrown when conversion not possible (should not happen).
01113    */
01114   virtual const pdSlewRate_t PDSR_val_2_pdSlewRate( const PDSR_val_t inPDSR_val) const;
01115 
01116   /** Convert value of type pdSlewRate_t to PDSR_val_t.
01117       @throw  internal_error  Thrown when conversion not possible (should not happen).
01118    */
01119   virtual const PDSR_val_t pdSlewRate_2_PDSR_val( const pdSlewRate_t inPdSlewRate_t) const;
01120 
01121   /** Convert value of type W1LT_val_t to w1LowTime_t.
01122       @throw  internal_error  Thrown when conversion not possible (should not happen).
01123    */
01124   virtual const w1LowTime_t W1LT_val_2_w1LowTime( const W1LT_val_t inW1LT_val) const;
01125 
01126   /** Convert value of type w1LowTime_t to W1LT_val_t.
01127       @throw  internal_error  Thrown when conversion not possible (should not happen).
01128    */
01129   virtual const W1LT_val_t w1LowTime_2_W1LT_val( const w1LowTime_t inW1LowTime) const;
01130 
01131   /** Convert value of type SOW0RT_val_t to soW0RecTime_t.
01132       @throw  internal_error  Thrown when conversion not possible (should not happen).
01133    */
01134   virtual const soW0RecTime_t SOW0RT_val_2_soW0RecTime( const SOW0RT_val_t inSOW0RT_val) const;
01135 
01136   /** Convert value of type soW0RecTime_t to SOW0RT_val_t.
01137       @throw  internal_error  Thrown when conversion not possible (should not happen).
01138    */
01139   virtual const SOW0RT_val_t soW0RecTime_2_SOW0RT_val( const soW0RecTime_t inSoW0RecTime) const;
01140 
01141   /** Convert value of type OWSPEED_val_t to wireSpeed_t.
01142       @throw  internal_error  Thrown when conversion not possible (should not happen).
01143    */
01144   virtual const wireSpeed_t OWSPEED_val_2_wireSpeed( const OWSPEED_val_t inOWSPEED_val) const;
01145   
01146   /** Convert value of type wireSpeed_t to OWSPEED_val_t.
01147       @throw  internal_error  Thrown when conversion not possible (should not happen).
01148    */
01149   virtual const OWSPEED_val_t wireSpeed_2_OWSPEED_val( const wireSpeed_t inWireSpeed) const;
01150 
01151   /** Convert value of type strongPullup_t to factor of 16ms.
01152       @throw  internal_error  Thrown when conversion not possible (should not happen).
01153    */
01154   virtual const uint8_t strongPullup_2_spFactor( const strongPullup_t inPullup) const;
01155 
01156   /** Convert value of type progPulse_t to factor of 8us.
01157       @throw  internal_error  Thrown when conversion not possible (should not happen).
01158    */
01159   virtual const uint8_t progPulse_2_ppFactor( const progPulse_t inPulse) const;
01160   //@}
01161     
01162 };
01163 
01164 #endif

Generated on Mon Oct 27 22:56:09 2003 by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001