0.4.1 DS3232

libraries/DS3232/CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.1] - 2024-05-17
+- add **float getTemperature()**
+- make DS3231 the base class as the DS3232 has EEPROM (logical)
+- add experimental SRAM support 
+  - **SRAMwrite8/16/32()** + **SRAMread8/16/32()**
+- add example to test SRAM for DS3232.
+- update readme.md.
+- minor edits
+
 ## [0.4.0] - 2024-04-05
 - fix #2, add **setWeekDay()**
 - update examples

libraries/DS3232/DS3232.cpp

@@ -2,7 +2,7 @@
 //    FILE: DS3232.cpp
 //  AUTHOR: Rob Tillaart
 // PURPOSE: Arduino library for DS3232 RTC (minimalistic)
-// VERSION: 0.4.0
+// VERSION: 0.4.1
 //    DATE: 2011-01-21
 //     URL: https://github.com/RobTillaart/DS3232
 
@@ -14,11 +14,11 @@
 //
 //  CONSTRUCTOR
 //
-DS3232::DS3232(TwoWire *wire)
+DS3231::DS3231(TwoWire *wire)
 {
   _wire     = wire;
   _address  = 0x68;  //  fixed.
-  _type     = 3232;
+  _type     = 3231;
   _lastRead = 0;
   for (int i = 0; i < 7; i++)
   {
@@ -27,14 +27,14 @@ DS3232::DS3232(TwoWire *wire)
 }
 
 
-int DS3232::begin()
+int DS3231::begin()
 {
   if (! isConnected() ) return DS3232_ERROR_CONNECT;
   return DS3232_OK;
 }
 
 
-bool DS3232::isConnected()
+bool DS3231::isConnected()
 {
   _wire->beginTransmission(_address);
   _rv = _wire->endTransmission();
@@ -42,13 +42,13 @@ bool DS3232::isConnected()
 }
 
 
-uint8_t DS3232::getAddress()
+uint8_t DS3231::getAddress()
 {
   return _address;
 }
 
 
-uint16_t DS3232::getType()
+uint16_t DS3231::getType()
 {
   return _type;
 }
@@ -58,7 +58,7 @@ uint16_t DS3232::getType()
 //
 //  CORE
 //
-int DS3232::read()
+int DS3231::read()
 {
   _wire->beginTransmission(_address);
   _wire->write(DS3232_SECONDS);
@@ -81,7 +81,7 @@ int DS3232::read()
 }
 
 
-int DS3232::write()
+int DS3231::write()
 {
   _wire->beginTransmission(_address);
   _wire->write(DS3232_SECONDS);
@@ -103,7 +103,7 @@ int DS3232::write()
 }
 
 
-uint32_t DS3232::lastRead()
+uint32_t DS3231::lastRead()
 {
   return _lastRead;
 }
@@ -113,33 +113,46 @@ uint32_t DS3232::lastRead()
 //
 //  GETTERS
 //
-uint8_t DS3232::seconds() { return _reg[0]; }
+uint8_t DS3231::seconds() { return _reg[0]; }
-uint8_t DS3232::minutes() { return _reg[1]; }
+uint8_t DS3231::minutes() { return _reg[1]; }
-uint8_t DS3232::hours()   { return _reg[2]; }
+uint8_t DS3231::hours()   { return _reg[2]; }
-uint8_t DS3232::weekDay() { return _reg[3]; }
+uint8_t DS3231::weekDay() { return _reg[3]; }
-uint8_t DS3232::day()     { return _reg[4]; }
+uint8_t DS3231::day()     { return _reg[4]; }
-uint8_t DS3232::month()   { return _reg[5]; }
+uint8_t DS3231::month()   { return _reg[5]; }
-uint8_t DS3232::year()    { return _reg[6]; }
+uint8_t DS3231::year()    { return _reg[6]; }
 
 
 /////////////////////////////////////////////////////////
 //
 //  SETTERS
 //
-void DS3232::setSeconds(uint8_t value) { _reg[0] = value; }
+void DS3231::setSeconds(uint8_t value) { _reg[0] = value; }
-void DS3232::setMinutes(uint8_t value) { _reg[1] = value; }
+void DS3231::setMinutes(uint8_t value) { _reg[1] = value; }
-void DS3232::setHours(uint8_t value)   { _reg[2] = value; }
+void DS3231::setHours(uint8_t value)   { _reg[2] = value; }
-void DS3232::setWeekDay(uint8_t value) { _reg[3] = value; }
+void DS3231::setWeekDay(uint8_t value) { _reg[3] = value; }
-void DS3232::setDay(uint8_t value)     { _reg[4] = value; }
+void DS3231::setDay(uint8_t value)     { _reg[4] = value; }
-void DS3232::setMonth(uint8_t value)   { _reg[5] = value; }
+void DS3231::setMonth(uint8_t value)   { _reg[5] = value; }
-void DS3232::setYear(uint8_t value)    { _reg[6] = value; }
+void DS3231::setYear(uint8_t value)    { _reg[6] = value; }
+
+
+/////////////////////////////////////////////////////////
+//
+//  TEMPERATURE
+//
+float DS3231::getTemperature()
+{
+  float temperature = (int8_t)readRegister(DS3232_TEMPERATURE);
+  int   fraction = readRegister(DS3232_TEMPERATURE + 1);
+  if (fraction != 0) temperature += (fraction >> 6) * 0.25;
+  return temperature;
+}
 
 
 /////////////////////////////////////////////////////////
 //
 //  LOW LEVEL
 //
-int DS3232::readRegister(uint8_t reg)
+int DS3231::readRegister(uint8_t reg)
 {
   _wire->beginTransmission(_address);
   _wire->write(reg);
@@ -154,7 +167,7 @@ int DS3232::readRegister(uint8_t reg)
 }
 
 
-int DS3232::writeRegister(uint8_t reg, uint8_t value)
+int DS3231::writeRegister(uint8_t reg, uint8_t value)
 {
   _wire->beginTransmission(_address);
   _wire->write(reg);
@@ -170,13 +183,13 @@ int DS3232::writeRegister(uint8_t reg, uint8_t value)
 //  PRIVATE
 //
 
-uint8_t DS3232::dec2bcd(uint8_t value)
+uint8_t DS3231::dec2bcd(uint8_t value)
 {
   return value + 6 * (value / 10);
 }
 
 
-uint8_t DS3232::bcd2dec(uint8_t value)
+uint8_t DS3231::bcd2dec(uint8_t value)
 {
   return value - 6 * (value >> 4);
 }
@@ -190,11 +203,68 @@ uint8_t DS3232::bcd2dec(uint8_t value)
 
 /////////////////////////////////////////////////////////////////////////////
 //
-//  DS3231
+//  DS3232
 //
-DS3231::DS3231(TwoWire *wire) : DS3232(wire)
+DS3232::DS3232(TwoWire *wire) : DS3231(wire)
 {
-  _type = 3231;
+  _type = 3232;
+}
+
+
+//
+//  SRAM 236 bytes, register 0x14-0xFF
+//  index = 0x00..0xEB == 0..235
+//  note: no boundary check
+int DS3232::SRAMwrite8(uint8_t index, uint8_t value)
+{
+  uint8_t position = DS3232_SRAM_BASE + index;
+  return writeRegister(position, value);
+}
+
+int DS3232::SRAMwrite16(uint8_t index, uint16_t value)
+{
+  uint8_t position = DS3232_SRAM_BASE + index;
+  writeRegister(position, value >> 8);
+  return writeRegister(position + 1, value & 0xFF);
+}
+
+int DS3232::SRAMwrite32(uint8_t index, uint32_t value)
+{
+  uint32_t val = value;
+  uint8_t position = DS3232_SRAM_BASE + index;
+  for (int i = 0; i < 4; i++)
+  {
+    writeRegister(position + i, val & 0xFF);
+    val >>= 8;
+  }
+  return DS3232_OK;
+}
+
+uint8_t DS3232::SRAMread8(uint8_t index)
+{
+  uint8_t position = DS3232_SRAM_BASE + index;
+  return readRegister(position);
+}
+
+uint16_t DS3232::SRAMread16(uint8_t index)
+{
+  uint8_t position = DS3232_SRAM_BASE + index;
+  uint16_t val = readRegister(position);
+  val <<= 8;
+  val += readRegister(position + 1);
+  return val;
+}
+
+uint32_t DS3232::SRAMread32(uint8_t index)
+{
+  uint32_t val = 0;
+  uint8_t position = DS3232_SRAM_BASE + index;
+  for (int i = 3; i >= 0; i--)
+  {
+    val <<= 8;
+    val += readRegister(position + i);
+  }
+  return val;
 }
 
 

libraries/DS3232/DS3232.h

@@ -3,7 +3,7 @@
 //    FILE: DS3232.h
 //  AUTHOR: Rob Tillaart
 // PURPOSE: Arduino library for DS3232 RTC (minimalistic)
-// VERSION: 0.4.0
+// VERSION: 0.4.1
 //    DATE: 2011-01-21
 //     URL: https://github.com/RobTillaart/DS3232
 
@@ -12,7 +12,7 @@
 #include "Wire.h"
 
 
-#define DS3232_LIB_VERSION         "0.4.0"
+#define DS3232_LIB_VERSION         "0.4.1"
 
 
 //  ERROR CODES
@@ -33,22 +33,24 @@
 #define DS3232_SRAM_BASE            0x14
 
 
-class DS3232
+class DS3231
 {
 public:
-  //  CONSTRUCTOR
+  //  Constructor
-  DS3232(TwoWire *wire = &Wire);
+  DS3231(TwoWire *wire = &Wire);
   int      begin();
   bool     isConnected();
   uint8_t  getAddress();
   uint16_t getType();
 
+
   //  BASE RTC
   int      read();
   int      write();
   uint32_t lastRead();
 
-  //  GETTERS
+
+  //  Getters
   uint8_t  seconds();
   uint8_t  minutes();
   uint8_t  hours();
@@ -57,7 +59,8 @@ public:
   uint8_t  month();
   uint8_t  year();
 
-  //  SETTERS
+
+  //  Setters
   void     setSeconds(uint8_t value);
   void     setMinutes(uint8_t value);
   void     setHours(uint8_t value);
@@ -66,6 +69,9 @@ public:
   void     setMonth(uint8_t value);
   void     setYear(uint8_t value);
 
+  //  Temperature
+  float    getTemperature();
+
 
   //  LOW LEVEL access to all registers
   //  check datasheet for details of registers.
@@ -73,7 +79,7 @@ public:
   int      readRegister(uint8_t reg);
   int      writeRegister(uint8_t reg, uint8_t value);
 
-  //  DEBUG
+  //  Debug
   int      lastRv() { return _rv; };
 
 
@@ -86,7 +92,7 @@ protected:
   uint32_t  _lastRead = 0;
 
   int       _rv;
-  uint16_t  _type = 3232;
+  uint16_t  _type = 3231;
 
   uint8_t   dec2bcd(uint8_t value);
   uint8_t   bcd2dec(uint8_t value);
@@ -97,10 +103,27 @@ protected:
 //
 //  DERIVED CLASSES
 //
-class DS3231 : public DS3232
+class DS3232 : public DS3231
 {
 public:
-  DS3231(TwoWire *wire = &Wire);
+  DS3232(TwoWire *wire = &Wire);
+
+  //  EXPERIMENTAL SRAM SUPPORT
+  //
+  //  SRAM 236 bytes, register 0x14-0xFF
+  //  index = 0..235 == 0x00..0xEB
+  //  236 bytes = 59 x uint32_t (e.g. time stamps)
+  //  note: no boundary check
+  //  TODO: optimize read/write multiple bytes at once.
+  int      SRAMwrite8(uint8_t index, uint8_t value);
+  int      SRAMwrite16(uint8_t index, uint16_t value);
+  int      SRAMwrite32(uint8_t index, uint32_t value);
+  uint8_t  SRAMread8(uint8_t index);
+  uint16_t SRAMread16(uint8_t index);
+  uint32_t SRAMread32(uint8_t index);
+
+private:
+
 };
 
 

libraries/DS3232/README.md

@@ -41,14 +41,14 @@ from 2011 which was never published.
 
 #### Tests
 
-All examples are tested with Arduino UNO with 100KHz I2C.
+All 0.4.0 examples are tested with Arduino UNO with 100KHz I2C.
 
 
 #### Compatibles
 
 The DS3231 RTC is compatible for the date and time keeping part.
 The only difference found is that the DS3231 does not have the 
-236 bytes of **battery backupped** SRAM the DS3232 has.
+236 bytes of **battery back-upped** SRAM the DS3232 has.
 
 
 #### Related
@@ -166,6 +166,15 @@ Setters set a value, to update the RTC call **write()** after.
 Note: you can also adjust just one field and keep the others.
 
 
+#### Temperature
+
+Note that the temperature measurement is only refreshed every 64 (default),
+128, 256 or 512 seconds.
+The interval can be set with bits 5 and 4 of the CONTROL/STATUS register (0x0F).
+
+- **float getTemperature()** return temperature in 0.25°C steps.
+
+
 #### Low level: Read/WriteRegister
 
 Allows to access all functionality the library did not implement (yet).
@@ -184,6 +193,25 @@ of ```wire.EndTransmission()``` to get an indication of the problem.
 - **int lastRv()** values depend on platform used.
 
 
+## DS3232 SRAM 
+
+Experimental SRAM support, needs to be tested / verified.  
+Feedback welcome.
+
+SRAM is DS3232 specific, and it has 236 bytes.
+The following functions use index 0..235. The user should guard 
+the index esp. for the 16 and 32 bit versions as it is not checked.
+
+236 bytes can be used e.g. to hold 78 hms timestamps
+
+- **int SRAMwrite8(uint8_t index, uint8_t value)**
+- **int SRAMwrite16(uint8_t index, uint16_t value)**
+- **int SRAMwrite32(uint8_t index, uint32_t value)**
+- **uint8_t SRAMread8(uint8_t index)**
+- **uint16_t SRAMread16(uint8_t index)**
+- **uint32_t SRAMread32(uint8_t index)**
+
+
 ## Notes
 
 #### Day of week
@@ -202,6 +230,9 @@ why 0 == Thursday. Epoch (1-1-1970) is a Thursday.
 
 ## Future
 
+Idea: use the DS3231 as the small footprint version
+and allow the DS3232 to support all functionality.
+
 #### Must
 
 - improve documentation.
@@ -212,31 +243,35 @@ why 0 == Thursday. Epoch (1-1-1970) is a Thursday.
 - test performance / footprint
 - can the trick from the example be included in the library?
   - extra footprint?
+- test SRAM with a DS3232 (need hardware)
 
 #### Could
 
-DS3232_EXT class
 - add readDate() + readTime()
   - less IO
-  - as date is not read so often?
+  - as date is not read so often.
-- int getTemperature();
-- AM/PM support could be done in software.
-  - simpler than decoding RTC?
 
-
+DS3232 derived class SRAM - test
-DS3232EE class for SRAM 236 bytes 
+- int SRAMwriteFloat(uint8_t index, uint8_t value);
-- int SRAMwrite8(uint8_t index, uint8_t value);
+- float SRAMreadFloat(uint8_t index);
-- int SRAMwrite16(uint8_t index, uint16_t value);
+- float and char array support?  Template T;
-- int SRAMwrite32(uint8_t index, uint32_t value);
+- optimize SRAM read and write functions (performance)
-- int SRAMread8(uint8_t index, uint8_t value);
+  - writeRegister(idx, buf, size)
-- int SRAMread16(uint8_t index, uint16_t value);
-- int SRAMread32(uint8_t index, uint32_t value);
-- float and char array support?
 
 
 #### Wont
 
 Other extended functionality (or in derived class)
+- void startRTC();
+- void stopRTC();
+- bool isRunningRTC();
+- void setSQWMode(uint8_t);  //  0..3 ??
+- alarm 1 & 2, same reg array?
+- RESET pin input and output
+- AM/PM mode not supported, user can handle this easily
+  - bool is24Mode();
+  - void set24Mode();
+  - void set12Mode();
 
 
 ## Support

libraries/DS3232/examples/DS3232_demo_getTemperature/DS3232_demo_getTemperature.ino

@@ -0,0 +1,49 @@
+//
+//    FILE: DS3232_demo_getTemperature.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: test basic getTemperature function
+//     URL: https://github.com/RobTillaart/DS3232
+
+
+#include "DS3232.h"
+
+
+DS3232 rtc;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println();
+  Serial.println(__FILE__);
+  Serial.print("DS3232_LIB_VERSION: ");
+  Serial.println(DS3232_LIB_VERSION);
+  Serial.println();
+
+  Wire.begin();
+  if (rtc.begin() != DS3232_OK)
+  {
+    Serial.println("could not connect, check wires etc");
+    while (1);
+  }
+}
+
+
+void loop()
+{
+  rtc.read();
+
+  Serial.print(rtc.hours());
+  Serial.print(':');
+  Serial.print(rtc.minutes());
+  Serial.print(':');
+  Serial.print(rtc.seconds());
+  Serial.print('\t');
+  Serial.print(rtc.getTemperature());
+  Serial.print('\n');
+
+  delay(2000);
+}
+
+
+//  --  END OF FILE  --

libraries/DS3232/examples/DS3232_demo_write/DS3232_demo_write.ino

@@ -63,6 +63,7 @@ void printDate(Stream &str)
   str.print(buffer);
 }
 
+
 void printTime(Stream &str)
 {
   char buffer[16];
@@ -71,4 +72,5 @@ void printTime(Stream &str)
   str.print(buffer);
 }
 
+
 //  --  END OF FILE  --

libraries/DS3232/examples/DS3232_test_SRAM/DS3232_test_SRAM.ino

@@ -0,0 +1,75 @@
+//
+//    FILE: DS3232_test_SRAM.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: test basic write function
+//     URL: https://github.com/RobTillaart/DS3232
+//
+//  NOTE: does NOT work for DS3231
+//        (only for DS3232)
+
+#include "DS3232.h"
+
+DS3232 rtc;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println();
+  Serial.println(__FILE__);
+  Serial.print("DS3232_LIB_VERSION: ");
+  Serial.println(DS3232_LIB_VERSION);
+  Serial.println();
+
+  Wire.begin();
+  if (rtc.begin() != DS3232_OK)
+  {
+    Serial.println("could not connect, check wires etc");
+    // while (1);
+  }
+
+  //  CLEAR SRAM
+  for (uint32_t i = 0; i < 236; i++)
+  {
+    rtc.SRAMwrite8(i, 0);
+    Serial.print(i);
+    Serial.print('\t');
+    Serial.println(rtc.SRAMread8(i));
+  }
+
+  //  write values / read back  8 bit
+  for (uint32_t i = 0; i < 236; i++)
+  {
+    rtc.SRAMwrite8(i, i);
+    Serial.print(i);
+    Serial.print('\t');
+    Serial.println(rtc.SRAMread8(i));
+  }
+
+  //  write values / read back 16 bit
+  for (uint32_t i = 0; i < 236; i += 2)
+  {
+    rtc.SRAMwrite16(i, 1000 + i);
+    Serial.print(i);
+    Serial.print('\t');
+    Serial.println(rtc.SRAMread16(i));
+  }
+
+  //  write values / read back 32 bit
+  for (uint32_t i = 0; i < 236; i += 4)
+  {
+    rtc.SRAMwrite32(i, 2000 + i);
+    Serial.print(i);
+    Serial.print('\t');
+    Serial.println(rtc.SRAMread32(i));
+  }
+}
+
+
+void loop()
+{
+
+}
+
+
+//  --  END OF FILE  --

libraries/DS3232/keywords.txt

@@ -31,12 +31,23 @@ setDay	KEYWORD2
 setMonth	KEYWORD2
 setYear	KEYWORD2
 
+getTemperature	KEYWORD2
+
 readRegister	KEYWORD2
 writeRegister	KEYWORD2
 
 lastRv	KEYWORD2
 
 
+# DS3232 specific
+SRAMwrite8	KEYWORD2
+SRAMwrite16	KEYWORD2
+SRAMwrite32	KEYWORD2
+SRAMread8	KEYWORD2
+SRAMread16	KEYWORD2
+SRAMread32	KEYWORD2
+
+
 # Constants (LITERAL1)
 DS3232_LIB_VERSION	LITERAL1
 

libraries/DS3232/library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/DS3232.git"
   },
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

libraries/DS3232/library.properties

@@ -1,5 +1,5 @@
 name=DS3232
-version=0.4.0
+version=0.4.1
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for I2C DS3232 RTC (minimalistic).