diff --git a/MCP9802.cpp b/MCP9802.cpp index 3ca7fee..da01ea5 100644 --- a/MCP9802.cpp +++ b/MCP9802.cpp @@ -228,9 +228,9 @@ void MCP9802::setLimit(float newLimit) { void MCP9802::reset() { _singleConfig = CONT; _tempUnit = CELSIUS; + setTempUnit(CELSIUS); setConMode(SINGLE); // check if needed setConfig(DEFAULT_CONFIG); - setTempUnit(CELSIUS); setHyst(DEFAULT_HYST); setLimit(DEFAULT_LIMIT); } diff --git a/MCP9802.h b/MCP9802.h index 91a25c1..89c4f84 100644 --- a/MCP9802.h +++ b/MCP9802.h @@ -169,7 +169,6 @@ typedef enum:byte { } temp_unit_t; // update readme -// update keywords class MCP9802 { public: diff --git a/README.md b/README.md index 597a6e8..2abfa25 100755 --- a/README.md +++ b/README.md @@ -5,18 +5,20 @@ The MCP9802 is a 9 to 12-Bit Single-Channel Temperature Sensor with Hysteresis & Alert capabilities and hardware I2C interface. -This library contains a robust driver for the MCP9802 which exposes all its Configuration, Hysteresis, Limit & Alert Settings; working in degrees Celsius or Fahrenheit; and, Integer or Floating-Point data manipulation. +This library contains a robust driver for the MCP9802 which exposes all its Configuration, Hysteresis, Limit & Alert Settings in degrees Celsius or Fahrenheit. ## Repository Contents * **MCP9802.h** - Header file of the library. * **MCP9802.cpp** - Compilation file of the library. -* **DegreeConverter.h** - Header file for Library helper methods. -* **DegreeConverter.cpp** - Compilation file for Library helper methods. +* **/utility** - +- **MCP9802InfoStr.h** - Header file containing a functional extention of the library to include generating pritable information String (see note #9 below) +- **MCP9802ComStr.h** - Header file containing a functional extention of the library to include generating pritable I2C Communication Result String (see note #10 below) * **/examples** - -- **/MCP9802_Test/MCP9802_Test.ino** - A basic sketch for testing the MCP9802 is hooked-up and operating correctly. -- **MCP9802_Usage/MCP9802_Usage.ino** - A much more detailed sketch offering a complete usage illustration, as well as a rubust testing mechanism. -- **/MCP9802_Info/MCP9802_Info.ino** - A short sketch showing how to generate a printable device information String of the MCP9802's current settings (i.e. Configuration, Limit &anp; Hysteresis registers). +- **/MCP9802_Test/MCP9802_Test.ino** - A basic sketch for testing the MCP9802 is hooked-up and operating correctly +- **MCP9802_Usage/MCP9802_Usage.ino** - A much more detailed sketch offering a complete usage illustration, as well as a rubust testing mechanism +- **/MCP9802_Info/MCP9802_Info.ino** - A short sketch showing how to generate a printable device information String of the MCP9802's current settings (i.e. Configuration, Limit &anp; Hysteresis registers) +- **/MCP9802_I2C_Status/MCP9802_I2C_Status.info** - A short test for verifying I2C communication has been set up properly with the device * **/extras** - Complementary documentation (End-User License, etc.) * **keywords.txt** - Keywords for this library which will be highlighted in sketches within the Arduino IDE. * **library.properties** - General library properties for the Arduino package manager. @@ -48,52 +50,46 @@ to this: ``` As noted above, whichever library you intend to use for this purpose __must be alredy installed__ for the MCP9802 library to work. -__2. Shutdown & Conversion Mode__ +2) __Device Temperature Range__ -The first bit of the configuration byte controls the device mode of operation, namely: ON, in which the device operates in 'CONTINUOUS' mode, -or OFF - or more precisely HYBERNATE (as I2C communication remains active), in which the device operates in 'SINGLE-SHOT' nmode. As such, setting -the 'CONVERSION MODE' of the device to 'CONTINUOUS' will effectively ensure that it is 'ON', while setting it to 'SINGLE-SHOT' mode will turn it OFF -(or more accurately, put it in hybernate mode). +The MCP9802 is designed to measure temperature btween -55°C to 125°C (-67°F to 257°F). Measurments below or above this range will return the minimum or maximum measurable value. Concurently, the ability to custom set the HYSTERESIS or LIMIT values has been limited to thisrange in software (even though logically, these values would need to be al least slightly lower or higher with respect to the actual measurable temperature). -__3. Hysteresis & Limit Registers Resolution__ +3) __Shutdwon & Conversion Mode__ -The Temperature register has a setteble range of 9 to 12-BIT (0.5 to 0.0625 degrees Celsius respectively). However, both the LIMIT and HYSTERESIS -registers only have a 9-BIT fixed resolution. This means these registers can only be set with a maximum resolution of 0.5 degrees Celsius. -Hence, while the relevant functions (e.g. setTempC(); ) will happily accept any float value within the premmitted parameter range (-55C to 125C) -for either of these two registers, this float value will be automatically rounded to the nearest 0.5C. +The first bit of the configuration byte controls the device mode of operation, namely: ON, in which the device operates in 'CONTINUOUS' mode, or OFF - or more precisely HYBERNATE (as I2C communication remains active), in which the device operates in 'SINGLE-SHOT' nmode. As such, setting the 'CONVERSION MODE' of the device to 'CONTINUOUS' will effectively ensure that it is 'ON', while setting it to 'SINGLE-SHOT' mode will turn it OFF (or, rather, put it in hybernate mode). -__4. Degrees Celsius & Fahrenheit__ +4) __Hysteresis & Limit Registers Resolution__ -The libraty offers the option of getting/setting all termperature values (Abmient [read-only], Limit [read-write] and/or Hysteresis [read-write]) -in either degrees Celsuis or Fahrenheit. These can be obtained in a floating point format or, if prefered, in a x16 integer format to speed-up -conversion calculations and save memory space. +The Temperature register has a setteble range of 9 to 12-BIT (0.5 to 0.0625 degrees Celsius respectively). However, both the LIMIT and HYSTERESIS registers only have a 9-BIT fixed resolution. This means these registers can only be set with a maximum accuracy of 0.5 degrees Celsius. Hence, while the relevant functions (i.e. setHyst() and setLimit() ) will happily accept any float value within the premmitted parameter range (-55°C to 125°C) for either of these two registers, this float value will be automatically rounded to the nearest 0.5C. -__5. Degress Fahrenheit Precision Limitations__ +5) __Degrees Celsius & Fahrenheit__ -As the MCP9802 was designed primerily to work in a degree Celsuis scheme, all Fahrenheit values obtained (or custom set by the user) -can only represent approximations of the precise Celsius values generated or stored by the device. This limitation is particualarly -noticable when setting the LIMIT or HYSTERESIS registers to custom Fahrenheit values, as a double operation takes place, namely: -rounding the given value to the nearest 0.5 degree Celisus and the subsequent conversion of this figure to the equivalent Fahrenheit value. +The libraty offers the option of getting/setting all termperature values (Abmient [read-only], Limit [read-write] and/or Hysteresis [read-write]) in either degrees Celsuis or Fahrenheit (the default is degrees Celsius). -__6. Alert Output__ +6) __Degrees Fahrenheit Accuracy Limitation__ -The MCP9802's Alert functionality is based on an 'open collector' architecture which means it requires a pull-up resistor in order to work -(this is true for both Alert Types, i.e. 'ACTIVE-LOW' and 'ACTIVE-HIGH). For the purposes of this testing sketch, the Atmega's (weak) internal -pull-up resistor is used and so the only connection needed in this context is between the MCP9802's ALERT pin and the Arduino's Digital Pin D2. -However, for any real-life use of the device, it is highly recommended to implement a suitable external pull-up resistor (typically 10K) -hooked-up betweem the ALERT pin and VCC. +As the MCP9802 was designed to work in a degrees Celsuis scheme, all Fahrenheit values obtained (or custom set by the user) can only represent as close approximations as possible with relation to the Celsius values generated or stored by the device. This limitation is perhaps most noticable when setting the LIMIT or HYSTERESIS registers to custom Fahrenheit values, as a double operation needs to take place, namely: conversion of this figure to the equivalent Celsius value and then rounding that value to the nearest 0.5 degree Celisus (the latter stems from the 9-BIT size of the HYSTERESIS & LIMIT registers as noted above). -__7. Device Information String__ +7) __Alert Functionality__ + +The MCP9802's Alert functionality is based on an 'open collector' architecture which means it requires a pull-up resistor in order to work (this is true for both Alert Types, i.e. 'ACTIVE-LOW' and 'ACTIVE-HIGH). For the purposes of this testing sketch, the Atmega's (weak) internal pull-up resistor is used and so the only connection needed in this context is between the MCP9802's ALERT pin and the Arduino's Digital Pin D2. However, for any real-life use of the device, it is highly recommended to implement a suitable external pull-up resistor (typically 10K) hooked-up betweem the ALERT pin and VCC. + +__8. Alert Output__ + +The MCP9802's Alert functionality is based on an 'open collector' architecture which means it requires a pull-up resistor in order to work (this is true for both Alert Types, i.e. 'ACTIVE-LOW' and 'ACTIVE-HIGH). For the purposes of this testing sketch, the Atmega's (weak) internal pull-up resistor is used and so the only connection needed in this context is between the MCP9802's ALERT pin and the Arduino's Digital Pin D2. However, for any real-life use of the device, it is highly recommended to implement a suitable external pull-up resistor (typically 10K) hooked-up betweem the ALERT pin and VCC. + +__9. Device Information String__ + +It is now possible to extend the MCP9802 Library to include a function for generating a pritable device information string showing all the relevant details about the devices current Configuration, Limit & Hysteresis settings. As the additional functionality comes at the cost of increased memory usage, it was implemented as an optional add-on rather than added directly to the core MCP9802 Library. See the [MCP9802_Info](https://github.com/nadavmatalon/MCP9802/blob/master/examples/MCP9802_Info/MCP9802_Info.ino) example sketch for detailed explanation and an actual usage demo. + +__10. Device I2C Communications String__ + +It is now possible to also extend the MCP9802 Library to include a function for generating a pritable I2C Communications string showing the result of each I2C transaction in a human-friendly way, something that may be useful, for example, during debugging sessions. As the additional functionality comes at the cost of increased memory usage, it was implemented as an optional add-on rather than added directly to the core MCP9802 Library. See the [MCP9802_I2C_Status](https://github.com/nadavmatalon/MCP9802/blob/master/examples/MCP9802_I2C_Status/MCP9802_I2C_Status.ino) example sketch for detailed explanation and an actual usage demo. -It is now possible to extend the MCP9802 Library to include a function for generating a pritable device information string showing all the -relevant details about the devices current Configuration, Limit & Hysteresis settings. As the additional functionality comes at the cost -of increased memory usage, it was implemented as an optional add-on rather than added directly to the core MCP9802 Library. See the -[MCP9802_Info](https://github.com/nadavmatalon/MCP9802/blob/master/examples/MCP9802_Info/MCP9802_Info.ino) example sketch for detailed explanation and an actual usage demo. ## I2C ADDRESSES -Each ADS1110 has 1 of 8 possible I2C addresses (factory hardwired & recognized by its specific part number & top marking -on the package itself): +Each ADS1110 has 1 of 8 possible I2C addresses (factory hardwired & recognized by its specific part number & top marking on the package itself): | PART NO. | BIN | HEX | DEC | MARKING | |-----------------|----------|------|-----|---------| @@ -147,66 +143,21 @@ Description:   Searches for the MCP9802 at the pre-defined I2C Bu 6 ... Timed-out while waiting for data to be sent
Returns:         byte -__getTempC16();__ -Parameters:   None -Description:   Returns current temperature reading in degrees Celsius times 16 -Returns:         int - -__getTempC();__ +__getTemp();__ Parameters:   None Description:   Returns current temperature reading in degrees Celsius Returns:          float -__getTempF16();__ -Parameters:   None -Description:   Returns current temperature reading in degrees Fahrenheit times 16 -Returns:         int - -__getTempF();__ -Parameters:   None -Description:   Returns current temperature reading in degrees Fahrenheit -Returns:         float - -__getHystC16();__ -Parameters:   None -Description:   Returns the current Hysteresis register value in degrees Celsius times 16 -Returns:         int - -__getHystC();__ +__getHyst();__ Parameters:   None Description:   Returns the current Hysteresis register value in degrees Celsius Returns:         float -__getHystF16();__ -Parameters:   None -Description:   Returns the current Hysteresis register setting in degrees Fahrenheit times 16 -Returns:         int - -__getHystF();__ -Parameters:   None -Description:   Returns the current Hysteresis register setting in degrees Fahrenheit -Returns:         float - -__getLimitC16();__ -Parameters:   None -Description:   Returns the current Limit register value in degrees Celsius times 16 -Returns:         int - -__getLimitC();__ +__getLimit();__ Parameters:   None Description:   Returns the current Limit register value in degrees Celsius Returns:         float -__getLimitF16();__ -Parameters:   None -Description:   Returns the current Limit register value in degrees Fahrenheit times 16 -Returns:         int - -__getLimitF();__ -Parameters:   None -Description:   Returns the current Limit register value in degrees Fahrenheit -Returns:         float - __getAlertType();__ Parameters:   None Description:   Returns the current alert type setting (0 = COMPARATOR / 1 = INTERRUPT) @@ -221,6 +172,7 @@ __getFaultQueue();__ Parameters:   None Description:   Returns the current Fault Queue setting (1 / 2 / 4 / 6 fault readings - i.e. below Hysteresis or above the Limit - before activating the alert) Returns:          byte + __getResolution();__ Parameters:   None Description:   Returns the current Resolution setting (9 = 9-BIT / 10 = 10-BIT / 11 = 11-BIT / 12 = 12-BIT) @@ -231,46 +183,27 @@ Parameters:   None Description:   Returns the current Conversion Mode setting (0 = CONTINUOUS / 1 = SINGLE-SHOT) Returns:         byte -__setHyst16();__ -Parameters:   int (range: -880 to +2000) -Description:   Sets the Hysteresis register value in degrees Celsius times 16 -Returns:         None - -__setHystC();__ -Parameters:   int / float (range: -55.0 to +125.0) -Description:   Sets the Hysteresis register value in degrees Celsius -Returns:         None - -__setHystF16();__ -Parameters:   int (range: 1072 - to +4112) -Description:   Sets the Hysteresis register value in degrees Fahrenheit times 16 -Returns:         None +__getTempUnit();__ +Parameters:   None +Description:   Returns the current Degrees Unit setting (0 = CELSIUS / 1 = FAHRENHEIT) +Returns:         byte -__setHystF();__ -Parameters:   int / float (range: -67.0 to +257.0) -Description:   Sets the Hysteresis register value in degrees Fahrenheit -Returns:         None +__singleCon();__ +Parameters:   None +Conditions:    Works only in __Single-Shot__ mode +Description:   Carries out a single conversion & returns a temperature reading in degrees Celsius +Returns:         float -__setLimitC16();__ -Parameters:   int (range: -880 to +2000) -Description:   Sets the Limit register value in degrees Celsius times 16 +__setHyst();__ +Parameters:   int / float (range: -55 to +125) +Description:   Sets the Hysteresis register value in degrees Celsius Returns:         None -__setLimitC();__ -Parameters:   int / float (range: -55.0 to +125.0) +__setLimit();__ +Parameters:   int / float (range: -55 to +125) Description:   Sets the Limit register value in degrees Celsius Returns:         None -__setLimitF16();__ -Parameters:   int (range: -1072 to 4112) -Description:   Sets the Limit register value in degrees Fahrenheit times 16 -Returns:         None - -__setLimitF();__ -Parameters:   int / float (range: -67.0 to +257.0) -Description:   Sets the Limit register value in degrees Fahrenheit -Returns:         None - __setAlertType();__ Parameters:   COMP / INT Description:   Sets the alert output type (COMPARATOR / INTERRUPT) @@ -296,6 +229,11 @@ Parameters:   CONT / SINGLE Description:   Sets the Conversion Mode (CONTINUOUS / SINGLE-SHOT) Returns:         None +__setTempUnit();__ +Parameters:   CELSIUS / FAHRENEHIT +Description:   Sets the Degree Unit type (CELSIUS / FAHRENEHIT) +Returns:         None + __reset();__ Parameters:   None Description:   Resets the device to power-up default settings (except for the TEMP Register which is Read-Only), as follows: @@ -307,46 +245,17 @@ Description:   Resets the device to power-up default settings (ex * FAULT-QUEUE:                     1 FAULT * RESOLUTION:                        9-BIT * CONVERSION MODE:          CONTINUOUS +* DEGREES TYPE:             CELSIUS * LIMIT (DATA):                        0xA000 (80°C) * HYST (DATA):                         0x9600 (75°C)
Returns:         None -__singleConC16();__ -Parameters:   None -Conditions:    Works only in __Single-Shot__ mode -Description:   Carries out a single conversion & returns a temperature reading in degrees Celsius times 16 -Returns:         int - -__singleConC();__ -Parameters:   None -Conditions:    Works only in __Single-Shot__ mode -Description:   Carries out a single conversion & returns a temperature reading in degrees Celsius -Returns:         float - -__singleConF16();__ -Parameters:   None -Conditions:    Works only in __Single-Shot__ mode -Description:   Carries out a single conversion & returns a temperature reading in degrees Fahrenheit times 16 -Returns:         int - -__singleConF();__ -Parameters:   None -Conditions:    Works only in __Single-Shot__ mode -Description:   Carries out a single conversion & returns a temperature reading in degrees Fahrenheit -Returns:         float - __getComResult();__ Parameters:   None Description:  Returns the latest I2C Communication result code (see Success/Error codes above) Returns:        byte -__getComMsg();__ -Parameters:   None -Description:  Returns the latest I2C Communication result in a human-friendly String format -Returns:        String - - __Destructor__ If you want to destruct an existing MCP9802 object, you can use the following method to do so: @@ -355,9 +264,9 @@ If you want to destruct an existing MCP9802 object, you can use the following me ``` >__NOTE__: replace the '__device_name__' above with the name of your MCP9802 device. -###Extended Functionality* +###Extended Functionality\* -(* requires an additional 'include' of the relevant *.h file as shown in the corresponding example sketches) +\(\* requires an additional 'include' of the relevant *.h file as shown in the corresponding example sketches\) __MCP9802ComStr();__ Parameters:   Name of an initialized MCP9802 instance @@ -372,9 +281,8 @@ Returns:        String ## RUNNING THE EXAMPLE SKETCHES 1) Hook-up the MCP9802 to the Arduino as explained above. -2) If you like, connect a LED with an appropriate series resistor between the MCP9802's ALERT pin (PIN 3) and ground -3) Upload the relevant example sketch to the Arduino. -4) Open the Serial Communications Window (make sure the baud-rate is set to 9600 or change them in the sketch to match your Serial Port buad rate). +2) Upload the relevant example sketch to the Arduino. +3) Open the Serial Communications Window \(make sure the baud-rate is set to 9600 or change it in the sketch to match your Serial Port's buad-rate\). ## BUG REPORTS @@ -384,10 +292,6 @@ Please report any issues/bugs/suggestions at the 'Issues' section of this Github ## LICENSE -This library is a free software; you can redistribute it and/or modify it under the terms of the -GNU General Public License as published by the Free Software Foundation; either version 3.0 of -the License, or any later version.This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -PARTICULAR PURPOSE. See the GNU General Public License for more details. +This library is a free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3.0 of the License, or any later version.This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. diff --git a/keywords.txt b/keywords.txt index d83fb2a..1343640 100644 --- a/keywords.txt +++ b/keywords.txt @@ -12,52 +12,30 @@ MCP9802 KEYWORD1 # Instances (KEYWORD2) ####################################### -Mcp9802 KEYWORD2 - ####################################### # Methods and Functions (KEYWORD2) ####################################### ping KEYWORD2 -getTempC16 KEYWORD2 -getTempC KEYWORD2 -getTempF16 KEYWORD2 -getTempF KEYWORD2 -getHystC16 KEYWORD2 -getHystC KEYWORD2 -getHystF16 KEYWORD2 -getHystF KEYWORD2 -getLimitC16 KEYWORD2 -getLimitC KEYWORD2 -getLimitF16 KEYWORD2 -getLimitF KEYWORD2 +getTemp KEYWORD2 +getHyst KEYWORD2 +getLimit KEYWORD2 getAlertType KEYWORD2 getAlertMode KEYWORD2 getFaultQueue KEYWORD2 getResolution KEYWORD2 getConMode KEYWORD2 getTempUnit KEYWORD2 -getTempMultiplier KEYWORD2 setAlertType KEYWORD2 setAlertMode KEYWORD2 setFaultQueue KEYWORD2 setResolution KEYWORD2 setConMode KEYWORD2 setTempUnit KEYWORD2 -setTempMultiplier KEYWORD2 -setHystC KEYWORD2 -setHystC16 KEYWORD2 -setLimitC KEYWORD2 -setLimitC16 KEYWORD2 -setHystF KEYWORD2 -setHystF16 KEYWORD2 -setLimitF KEYWORD2 -setLimitF16 KEYWORD2 +setHyst KEYWORD2 +setLimit KEYWORD2 reset KEYWORD2 -singleConC KEYWORD2 -singleConF KEYWORD2 -singleConC16 KEYWORD2 -singleConF16 KEYWORD2 +singleCon KEYWORD2 getComResult KEYWORD2 MCP9802ComStr KEYWORD2 MCP9802InfoStr KEYWORD2 @@ -67,14 +45,13 @@ MCP9802InfoStr KEYWORD2 ####################################### DEFAULT_CONFIG LITERAL1 -INIT_SINGLE_SHOT LITERAL1 -DEFAULT_HYST_C LITERAL1 -DEFAULT_HYST_F LITERAL1 -DEFAULT_LIMIT_C LITERAL1 -DEFAULT_LIMIT_F LITERAL1 +DEFAULT_HYST LITERAL1 +DEFAULT_HYST LITERAL1 MIN_CON_TIME LITERAL1 CONFIG_BYTE LITERAL1 DATA_BYTES LITERAL1 +C_TO_F_CONST LITERAL1 +INIT_SINGLE_SHOT LITERAL1 COMP LITERAL1 INT LITERAL1 ACTIVE_LOW LITERAL1 @@ -91,8 +68,6 @@ CONT LITERAL1 SINGLE LITERAL1 CELSIUS LITERAL1 FAHRENHEIT LITERAL1 -NONE LITERAL1 -TIMES_16 LITERAL1 ####################################### # Built-In Variables (LITERAL2) @@ -105,4 +80,3 @@ fault_queue_t LITERAL2 resolution_t LITERAL2 con_mode_t LITERAL2 temp_unit_t LITERAL2 -temp_multi_t LITERAL2 diff --git a/library.properties b/library.properties index 082f7c0..62aa0d3 100644 --- a/library.properties +++ b/library.properties @@ -3,7 +3,7 @@ version=1.0.0 author=Nadav Matalon maintainer=Nadav Matalon sentence=MCP9802 Driver: 12-bit Temperature Sensor with an I2C Interface -paragraph=This library contains a robust driver for the MCP9802 which exposes all its Configuration, Hysteresis, Limit & Alert Settings; working in degrees Celsius or Fahrenheit; and, Integer or Floating-Point data manipulation. +paragraph=This library contains a robust driver for the MCP9802 which exposes all its Configuration, Hysteresis, Limit & Alert Settings in degrees Celsius or Fahrenheit; url=https://github.com/nadavmatalon/MCP9802 category=Sensors architectures=avr \ No newline at end of file