This class provides simplified I2C access to a MAXIM DS130x Real-Time Clock device, even if the LPC1768 has an embedded RTC module. My objective is to share the same RTC with Microchip 18F MCU.
Diff: DS130x_I2C.h
- Revision:
- 0:a1b58e3c9fdb
- Child:
- 1:834e9897e269
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/DS130x_I2C.h Wed Feb 09 13:43:21 2011 +0000 @@ -0,0 +1,392 @@ +/* mbed simplified access to MAXIM DS130x Serial, I2C Real-Time Clock + * Copyright (c) 2011 ygarcia + * + * of this software and associated documentation files (the "Software"), to deal + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +#if !defined(__DS130X_I2C_H__) +#define __DS130X_I2C_H__ + +#include <string> +#include <vector> + +#include "Debug.h" // Include mbed header + debug primitives. See DebugLibrary + +namespace DS130X_I2C { + /** This class provides simplified I2C access to a MAXIM DS130x Real-Time Clock device. V0.0.0.1 + * + * A typical use case should be the Mbed which acts as a time server with an ethernet connection, it synchronyzes a RTC circuit for all other module (Microchip/ATiny MCUs). + * + * Note that if the LPC1768 is powered in 3.3V and MAXIM DS130x Real-Time Clock device should be powered at 5V. + * In this case, you shall use a bi-directional level shifter for I2C-bus. Please refer to AN97055 (http://ics.nxp.com/support/documents/interface/pdf/an97055.pdf) + * MAXIM DS130x Real-Time Clock device reference: http://pdfserv.maxim-ic.com/en/ds/DS1307.pdf + * + * Note that for I2C details, please visit http://www.datelec.fr/fiches/I2C.htm + * + * Note that this header file include following headers: + * - <string> + * - <vector> + * - <mbed.h> + * + * @remark This class was validated with Tektronix TDS2014 oscilloscope in 3.3V and in mixte power mode 3.3V for mbed and 5V for the MAXIM DS130x Real-Time Clock device + * @author Yann Garcia (Don't hesitate to contact me: garcia.yann@gmail.com) + */ + class CDS130X_I2C : public I2C { + + public: // Enumerated + /** OscillatorMode modes + */ + enum OscillatorMode { + One_Hz, //<! Oscillator set for 1Hz square signal generation + Four_KHz, //<! Oscillator set for 4096Hz square signal generation + Height_KHz, //<! Oscillator set for 8192Hz square signal generation + ThirtyTwo_KHz, //<! Oscillator set for 32768Hz square signal generation + Output //<! Oscillator is not used, @see _outputControlLevel for logocal outpout level + }; + + /** Time register format + */ + enum RegisterFormatEnum { + Binary, //<! Time register format is binary + Bcd //<! Time register format is BCD + }; + + /** Memory storage mode + */ + enum Mode { + LittleEndian, //<! Little Endian mode: 0xA0B70708 is stored as 08: MSB and A0 LSB + BigEndian //<! Little Endian mode: 0xA0B70708 is stored as AO: MSB and 08 LSB + }; + + /** Registers address + */ + enum RegisterEnum { + SecondsAddress = 0x00, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + MinutesAddress = 0x01, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + HoursAddress = 0x02, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + DayOfWeekAddress = 0x03, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + DayAddress = 0x04, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + MonthAddress = 0x05, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + YearAddress = 0x06, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + ControlRegisterAddress = 0x07, //<! The register addresses for DS1307 - See Datasheet - Table 2. Timekeeper Registers + BaseMemoryAddress = 0x08 //<! First address of the memory area + }; + + private: // Internal data structures + + /** String used to convert day of week string into numerical value + */ + std::string _dayOfWeek; + + /** This method controls the clock halting or starting it + * + * See datasheet - Clause CLOCK AND CALENDAR (CH bit) + * + * @param p_mode: true to restart the clock, false to halt it + * @return true on success, false otherwise + */ + bool ControlClock(bool p_mode); + + /** The slave address byte for DS130x - See Datasheet - Figure 4. Data Write-Slave Receiver Mode + */ + unsigned char _slaveAddress; + /** Enable/disable the oscillator output + */ + CDS130X_I2C::OscillatorMode _oscillatorMode; + /** This flag controls the output level of the SQW/OUT pin when the square-wave output is disabled + * Set to true if OUT level should be logic level 1, false otherwise + */ + bool _outputLevel; + + public: // Construction methods + /** Ctor with Write Protect command pin wired + * + * @param p_slaveAddress: I2C device address + * @param p_sda: MBed pin for SDA + * @param p_scl: MBed pin for SCL + * @param p_oscillatorMode Indicate the oscillator mode (pin 7 - SQW/OUT). Default: Output (oscillator not used) + * @param p_outputLevel Indicate the output level (0V/Vdd) when oscillator mode is Output. Default: 0V + * @param p_frequency: Frequency of the I2C interface (SCL), default value is 100KHz - See datasheet - Clause I2C DATA BUS + */ + CDS130X_I2C(const unsigned char p_slaveAddress, const PinName p_sda, const PinName p_scl, const CDS130X_I2C::OscillatorMode p_oscillatorMode = Output, const bool p_outputLevel = false, const int p_frequency = 400000); + + /** Dtor + */ + virtual ~CDS130X_I2C(); + + /** Initialize the module, configuring the module and starting the clock + * + * @return true on success, false otherwise + */ + bool Initialize(); + + public: // Time part + /** This methods converts a packed BCD value < 99 into an hexadecimal value (e.g. 0x32 -> 0x10) + * + * @param p_hexaValue: The hexadecimal value to convert + * @return The packed BCD value + */ + inline unsigned char ConvertBCDToHex(const unsigned char p_bcdValue) { + return (unsigned char)((unsigned char)(p_bcdValue >> 4) * 10) + (unsigned char)(p_bcdValue & 0x0f); + } + + /** This methods converts an hexadecimal value < 99 into a packed BCD (e.g. 0x20 -> 0x32) + * + * @param p_hexaValue: The hexadecimal value to convert + * @return The packed BCD value + */ + inline unsigned char ConvertHexToBCD(const unsigned char p_hexaValue) { + return (p_hexaValue / 10) << 4 + (p_hexaValue % 10); + } + + /** Restart the clock + * + * See datasheet - Clause CLOCK AND CALENDAR (CH bit) + * + * @return true on success, false otherwise + */ + bool RestartClock(); + /** Halt the clock + * + * See datasheet - Clause CLOCK AND CALENDAR (CH bit) + * + * @return true on success, false otherwise + */ + bool HaltClock(); + + /** This method reads the DS130x time registers value in BCD or binary format + * + * See datasheet - Clause CLOCK AND CALENDAR + * + * @param p_address: The time register identifier the to read + * @param p_byte: The register value in BDC format + * @param p_format: The format of the value to return. Default is BCD + * @return true on success, false otherwise + * @see RegisterEnum + * @see RegisterFormatEnum + */ + bool Read(const RegisterEnum p_address, unsigned char * p_byte, const CDS130X_I2C::RegisterFormatEnum p_format = Bcd); + + /** This method writes a value (provided in BCD or binary format) into the specified DS130x register + * + * See datasheet - Clause CLOCK AND CALENDAR + * + * @param p_address: The time register identifier the to write + * @param p_byte: The value to write in BCD format + * @param p_format: The format of the value 'p_byte'. Default is BCD + * @return true on success, false otherwise + * @see RegisterEnum + * @see RegisterFormatEnum + */ + bool Write(const RegisterEnum p_address, const unsigned char p_byte, const CDS130X_I2C::RegisterFormatEnum p_format = Bcd); + + /** Set RTC time using string format "Www Mmm dd hh:mm:ss yyyy" + * + * @param p_utcTime: UTC string format + * @return true on success, false otherwise + */ + bool SetTime(const std::string p_utcTime); + + /** This methods returns the current time in string format "Www Mmm dd hh:mm:ss yyyy" + * + * @return The current time in C struct tm format + */ + struct tm GetTime(); + + public: // Memory part + /** Erase of memory area starting at the specified address, using the specified pattern to fill the memory area + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_count The size of the memory area to erase + * @param p_pattern The pattern value to use to fill the memory area. Defqult vqlue: 0x00 + * @return true on success, false otherwise + * Exemple: + * @code + * ... + * myRTC.EraseMemoryArea(0, 8); // Set to 0x00 the first heigh memory byte + * ... + * @endcode + */ + bool EraseMemoryArea(const unsigned char p_startAddress, const int p_count, unsigned char const p_pattern = 0x00); + + /** Write a byte at the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_byte The byte value to save. The address start from 0. + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const unsigned char p_byte); + + /** Write a short at the specified memory address according to the specified mode + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_short The short value to save + * @param p_mode The storage mode. Default value: BigEndian + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const short p_short, const CDS130X_I2C::Mode p_mode = BigEndian); + + /** Write an integer at the specified memory address according to the specified mode + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_int The integer value to save + * @param p_mode The storage mode. Default value: BigEndian + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const int p_int, const CDS130X_I2C::Mode p_mode = BigEndian); + + /** Write a buffer of bytes at the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_datas The string to save + * @param p_storeLength If true, store also the length of the buffer in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true. + * @param p_length2write The number of bytes to write, -1 for all characters. Default value: -1 + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const std::vector<unsigned char> & p_datas, bool p_storeLength = true, const int p_length2write = -1); + + /** Write a buffer of bytes at the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_datas The buffer of bytes to save + * @param p_storeLength If true, store also the length of the buffer in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true. + * @param p_length2write The number of bytes to write, -1 for all bytes. Default value: -1 + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const unsigned char *p_datas, bool p_storeLength = true, const int p_length2write = -1); + + /** Write a string at the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_string The string to save + * @param p_storeLength If true, store also the length of the string in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true. + * @param p_length2write The number of character to write, -1 for all characters + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const std::string & p_string, const bool p_storeLength = true, const int p_length2write = -1); + + /** Write a buffer of characters at the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * Note that the length of the buffer is not saved and the string is saved in Big Endian mode + * @param p_startAddress The address of the memory area. + * @param p_datas The string to save + * @param p_storeLength If true, store also the length of the string in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true. + * @param length2write The number of character to write, -1 for all characters + * @return true on success, false otherwise + */ + bool WriteMemory(const unsigned char p_address, const char *p_datas, const bool p_storeLength = true, const int p_length2write = -1); + + /** Read a byte from the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_byte The byte value to read + * @return true on success, false otherwise + */ + bool ReadMemory(const unsigned char p_address, unsigned char *p_value); + + /** Read a short from the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_short The short value to read + * @return true on success, false otherwise + */ + bool ReadMemory(const unsigned char p_address, short *p_short, const CDS130X_I2C::Mode p_mode = BigEndian); + + /** Read an integer from the specified memory address + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_int The integer value to read + * @return true on success, false otherwise + */ + bool ReadMemory(const unsigned char p_address, int *p_int, const CDS130X_I2C::Mode p_mode = BigEndian); + + /** Read a buffer of bytes from the specified memory address and store it into a std::vector<unsigned char> object + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that the size of the buffer object is used for the number of bytes to read + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_datas The buffer to fill + * @param p_readLengthFirst If true, read the length first and p_length2write parameter is ignored, otherwise the length is provided by p_length2write parameter. Default value: true + * @param p_length2write The number of character to write, -1 to use the size of the string buffer + * @return true on success, false otherwise + * Exemple: + * @code + * std::vector<unsigned char> datas(bufferLength); + * ... + * myEEPROM.Read(memoryAddress, datas); + * ... + * @endcode + */ + bool ReadMemory(const unsigned char p_address, std::vector<unsigned char> & p_datas, const bool p_readLengthFirst = true, const int p_length2write = -1); + + /** Read a buffer of characters from the specified memory address and store it into a string object + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that the size of the string object is used for the number of characters to read + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_string The string buffer to fill + * @param p_readLengthFirst If true, read the length first and p_length2write parameter is ignored, otherwise the length is provided by p_length2write parameter. Default value: true + * @param p_length2write The number of character to write, -1 to use the size of the string buffer + * @return true on success, false otherwise + */ + bool ReadMemory(const unsigned char p_address, std::string & p_string, const bool p_readLengthFirst = true, const int p_length2write = -1); + +#if defined(__DEBUG) + /** Dump a memory area + * + * Note that for the DS1307, the memory segment is [08h, 3Fh] + * Note that the size of the string object is used for the number of characters to read + * Note that this method only access the memeory registered. The memory address starts from 0x00 + * @param p_startAddress The address of the memory area. + * @param p_count The number of bytes toi dump + * @return true on success, false otherwise + */ + void DumpMemoryArea(const unsigned char p_address, const int p_count); +#endif // _DEBUG + }; // End of class CDS130X_I2C + +} // End of namespace DS130X_I2C + +using namespace DS130X_I2C; + +#endif // __DS130X_I2C_H__