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