This class provides simplified I2C access to a MAXIM DS130x Real-Time Clock device. More...

#include <DS130x_I2C.h>

Public Types
enum	OscillatorMode
	OscillatorMode modes. More...
enum	RegisterFormatEnum
	Time register format. More...
enum	Mode
	Memory storage mode. More...
enum	RegisterEnum
	Registers address. More...
Public Member Functions
	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)
	Ctor with Write Protect command pin wired.
virtual	~CDS130X_I2C ()
	Dtor.
bool	Initialize ()
	Initialize the module, configuring the module and starting the clock.
unsigned char	ConvertBCDToHex (const unsigned char p_bcdValue)
	This methods converts a packed BCD value < 99 into an hexadecimal value (e.g.
unsigned char	ConvertHexToBCD (const unsigned char p_hexaValue)
	This methods converts an hexadecimal value < 99 into a packed BCD (e.g.
bool	RestartClock ()
	Restart the clock.
bool	HaltClock ()
	Halt the clock.
bool	Read (const RegisterEnum p_address, unsigned char *p_byte, const CDS130X_I2C::RegisterFormatEnum p_format=Bcd)
	This method reads the DS130x time registers value in BCD or binary format.
bool	Write (const RegisterEnum p_address, const 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.
bool	SetTime (const std::string p_utcTime)
	Set RTC time using string format "Www Mmm dd hh:mm:ss yyyy".
struct tm	GetTime ()
	This methods returns the current time in string format "Www Mmm dd hh:mm:ss yyyy".
bool	EraseMemoryArea (const unsigned char p_startAddress, const int p_count, unsigned char const p_pattern=0x00)
	Erase of memory area starting at the specified address, using the specified pattern to fill the memory area.
bool	WriteMemory (const unsigned char p_address, const unsigned char p_byte)
	Write a byte at the specified memory address.
bool	WriteMemory (const unsigned char p_address, const short p_short, const CDS130X_I2C::Mode p_mode=BigEndian)
	Write a short at the specified memory address according to the specified mode.
bool	WriteMemory (const unsigned char p_address, const int p_int, const CDS130X_I2C::Mode p_mode=BigEndian)
	Write an integer at the specified memory address according to the specified mode.
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.
bool	WriteMemory (const unsigned char p_address, const unsigned char *p_datas, bool p_storeLength=true, const int p_length2write=-1)
	Write a buffer of bytes at the specified memory address.
bool	WriteMemory (const unsigned char p_address, const std::string &p_string, const bool p_storeLength=true, const int p_length2write=-1)
	Write a string at the specified memory address.
bool	WriteMemory (const unsigned char p_address, const char *p_datas, const bool p_storeLength=true, const int p_length2write=-1)
	Write a buffer of characters at the specified memory address.
bool	ReadMemory (const unsigned char p_address, unsigned char *p_value)
	Read a byte from the specified memory address.
bool	ReadMemory (const unsigned char p_address, short *p_short, const CDS130X_I2C::Mode p_mode=BigEndian)
	Read a short from the specified memory address.
bool	ReadMemory (const unsigned char p_address, int *p_int, const CDS130X_I2C::Mode p_mode=BigEndian)
	Read an integer from the specified memory address.
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 bytes from the specified memory address and store it into a std::vector<unsigned char> object.
bool	ReadMemory (const unsigned char p_address, std::string &p_string, 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.
void	DumpMemoryArea (const unsigned char p_address, const int p_count)
	Dump a memory area.

Detailed Description

This class provides simplified I2C access to a MAXIM DS130x Real-Time Clock device.

V0.0.0.2

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>

Remarks:: 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)

Definition at line 50 of file DS130x_I2C.h.

Member Enumeration Documentation

enum Mode

Memory storage mode.

Definition at line 72 of file DS130x_I2C.h.

enum OscillatorMode

OscillatorMode modes.

Definition at line 55 of file DS130x_I2C.h.

enum RegisterEnum

Registers address.

Definition at line 79 of file DS130x_I2C.h.

enum RegisterFormatEnum

Time register format.

Definition at line 65 of file DS130x_I2C.h.

Constructor & Destructor Documentation

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`
	)

Ctor with Write Protect command pin wired.

Parameters:

p_slaveAddress,:	I2C device address
p_sda,:	MBed pin for SDA
p_scl,:	MBed pin for SCL
p_oscillatorMode	Indicate the oscillator mode (pin 7 - SQW/OUT). Default: Output (oscillator not used)
p_outputLevel	Indicate the output level (0V/Vdd) when oscillator mode is Output. Default: 0V
p_frequency,:	Frequency of the I2C interface (SCL), default value is 100KHz - See datasheet - Clause I2C DATA BUS

Definition at line 7 of file DS130x_I2C.cpp.

~CDS130X_I2C ( ) [virtual]

Dtor.

Definition at line 18 of file DS130x_I2C.cpp.

Member Function Documentation

unsigned char ConvertBCDToHex ( const unsigned char p_bcdValue )

This methods converts a packed BCD value < 99 into an hexadecimal value (e.g.

0x32 -> 0x10)

Parameters:

p_hexaValue,: The hexadecimal value to convert

Returns:: The packed BCD value

Definition at line 145 of file DS130x_I2C.h.

unsigned char ConvertHexToBCD ( const unsigned char p_hexaValue )

This methods converts an hexadecimal value < 99 into a packed BCD (e.g.

0x20 -> 0x32)

Parameters:

p_hexaValue,: The hexadecimal value to convert

Returns:: The packed BCD value

Definition at line 163 of file DS130x_I2C.h.

void DumpMemoryArea	(	const unsigned char	p_address,
		const int	p_count
	)

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

Parameters:

p_startAddress	The address of the memory area.
p_count	The number of bytes toi dump

Returns:: true on success, false otherwise

Definition at line 571 of file DS130x_I2C.cpp.

bool EraseMemoryArea	(	const unsigned char	p_startAddress,
		const int	p_count,
		unsigned char const	p_pattern = `0x00`
	)

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

Parameters:

p_startAddress	The address of the memory area.
p_count	The size of the memory area to erase
p_pattern	The pattern value to use to fill the memory area. Defqult vqlue: 0x00

Returns:

true on success, false otherwise Exemple:

 ...
 myRTC.EraseMemoryArea(0, 8); // Set to 0x00 the first heigh memory byte
 ...

Definition at line 263 of file DS130x_I2C.cpp.

struct tm GetTime ( ) [read]

This methods returns the current time in string format "Www Mmm dd hh:mm:ss yyyy".

Returns:: The current time in C struct tm format

Definition at line 238 of file DS130x_I2C.cpp.

bool HaltClock ( )

Halt the clock.

See datasheet - Clause CLOCK AND CALENDAR (CH bit)

Returns:: true on success, false otherwise

Definition at line 80 of file DS130x_I2C.cpp.

bool Initialize ( )

Initialize the module, configuring the module and starting the clock.

Returns:: true on success, false otherwise

Definition at line 24 of file DS130x_I2C.cpp.

bool Read	(	const RegisterEnum	p_address,
		unsigned char *	p_byte,
		const CDS130X_I2C::RegisterFormatEnum	p_format = `Bcd`
	)

This method reads the DS130x time registers value in BCD or binary format.

See datasheet - Clause CLOCK AND CALENDAR

Parameters:

p_address,:	The time register identifier the to read
p_byte,:	The register value in BDC format
p_format,:	The format of the value to return. Default is BCD

Returns:: true on success, false otherwise

See also:: RegisterEnum; RegisterFormatEnum

Definition at line 112 of file DS130x_I2C.cpp.

bool ReadMemory	(	const unsigned char	p_address,
		int *	p_int,
		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

Parameters:

p_startAddress	The address of the memory area.
p_int	The integer value to read

Returns:: true on success, false otherwise

Definition at line 455 of file DS130x_I2C.cpp.

bool ReadMemory	(	const unsigned char	p_address,
		unsigned char *	p_value
	)

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

Parameters:

p_startAddress	The address of the memory area.
p_byte	The byte value to read

Returns:: true on success, false otherwise

Definition at line 404 of file DS130x_I2C.cpp.

bool ReadMemory	(	const unsigned char	p_address,
		short *	p_short,
		const CDS130X_I2C::Mode	p_mode = `BigEndian`
	)

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

Parameters:

p_startAddress	The address of the memory area.
p_short	The short value to read

Returns:: true on success, false otherwise

Definition at line 427 of file DS130x_I2C.cpp.

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 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

Parameters:

p_startAddress	The address of the memory area.
p_datas	The buffer to fill
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
p_length2write	The number of character to write, -1 to use the size of the string buffer

Returns:

true on success, false otherwise Exemple:

 std::vector<unsigned char> datas(bufferLength);
 ...
 myEEPROM.Read(memoryAddress, datas);
 ...

Definition at line 483 of file DS130x_I2C.cpp.

bool ReadMemory	(	const unsigned char	p_address,
		std::string &	p_string,
		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

Parameters:

p_startAddress	The address of the memory area.
p_string	The string buffer to fill
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
p_length2write	The number of character to write, -1 to use the size of the string buffer

Returns:: true on success, false otherwise

Definition at line 524 of file DS130x_I2C.cpp.

bool RestartClock ( )

Restart the clock.

See datasheet - Clause CLOCK AND CALENDAR (CH bit)

Returns:: true on success, false otherwise

Definition at line 76 of file DS130x_I2C.cpp.

bool SetTime ( const std::string p_utcTime )

Set RTC time using string format "Www Mmm dd hh:mm:ss yyyy".

Parameters:

p_utcTime,: UTC string format

Returns:: true on success, false otherwise

Definition at line 203 of file DS130x_I2C.cpp.

bool Write	(	const RegisterEnum	p_address,
		const 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

Parameters:

p_address,:	The time register identifier the to write
p_byte,:	The value to write in BCD format
p_format,:	The format of the value 'p_byte'. Default is BCD

Returns:: true on success, false otherwise

See also:: RegisterEnum; RegisterFormatEnum

Definition at line 158 of file DS130x_I2C.cpp.

bool WriteMemory	(	const unsigned char	p_address,
		const int	p_int,
		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

Parameters:

p_startAddress	The address of the memory area.
p_int	The integer value to save
p_mode	The storage mode. Default value: BigEndian

Returns:: true on success, false otherwise

Definition at line 316 of file DS130x_I2C.cpp.

bool WriteMemory	(	const unsigned char	p_address,
		const short	p_short,
		const CDS130X_I2C::Mode	p_mode = `BigEndian`
	)

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

Parameters:

p_startAddress	The address of the memory area.
p_short	The short value to save
p_mode	The storage mode. Default value: BigEndian

Returns:: true on success, false otherwise

Definition at line 290 of file DS130x_I2C.cpp.

bool WriteMemory	(	const unsigned char	p_address,
		const char *	p_datas,
		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

Parameters:

p_startAddress	The address of the memory area.
p_datas	The string to save
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.
length2write	The number of character to write, -1 for all characters

Returns:: true on success, false otherwise

Definition at line 364 of file DS130x_I2C.cpp.

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

Parameters:

p_startAddress	The address of the memory area.
p_datas	The string to save
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.
p_length2write	The number of bytes to write, -1 for all characters. Default value: -1

Returns:: true on success, false otherwise

Definition at line 351 of file DS130x_I2C.cpp.

bool WriteMemory	(	const unsigned char	p_address,
		const unsigned char	p_byte
	)

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

Parameters:

p_startAddress	The address of the memory area.
p_byte	The byte value to save. The address start from 0.

Returns:: true on success, false otherwise

Definition at line 270 of file DS130x_I2C.cpp.

bool WriteMemory	(	const unsigned char	p_address,
		const std::string &	p_string,
		const 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

Parameters:

p_startAddress	The address of the memory area.
p_string	The string to save
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.
p_length2write	The number of character to write, -1 for all characters

Returns:: true on success, false otherwise

Definition at line 346 of file DS130x_I2C.cpp.

bool WriteMemory	(	const unsigned char	p_address,
		const 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

Parameters:

p_startAddress	The address of the memory area.
p_datas	The buffer of bytes to save
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.
p_length2write	The number of bytes to write, -1 for all bytes. Default value: -1

Returns:: true on success, false otherwise

Definition at line 399 of file DS130x_I2C.cpp.

Type:	Library
Created:	09 Feb 2011
Imports:	27
Forks:	0
Commits:	2
Dependents:	0
Dependencies:	0
Followers:	2

CDS130X_I2C Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

CDS130X_I2C Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning