Meadow.Foundation.RTCs.Ds323x

Ds323x
Status
Source code	GitHub
Datasheet(s)	GitHub
NuGet package

The DS323x is a low-cost and accurate real-time clock with a temperature compensation crystal oscillator. This range of chips offers the following functionality:

• Temperature compensation
• Battery backup
• I2C (DS3231) and SPI (DS3234) interfaces.
• Two programmable alarms
• 32.768 KHz square wave output

Code Example

Ds3231 sensor;

public override Task Initialize()
{
    Resolver.Log.Info("Initialize...");

    sensor = new Ds3231(Device.CreateI2cBus(), Device.Pins.D06);
    sensor.OnAlarm1Raised += Sensor_OnAlarm1Raised;

    return base.Initialize();
}

public override Task Run()
{
    sensor.CurrentDateTime = new DateTime(2020, 1, 1);

    Resolver.Log.Info($"Current time: {sensor.CurrentDateTime}");
    Resolver.Log.Info($"Temperature: {sensor.Temperature}");

    sensor.ClearInterrupt(Ds323x.Alarm.BothAlarmsRaised);

    sensor.SetAlarm(Ds323x.Alarm.Alarm1Raised,
        new DateTime(2020, 1, 1, 1, 0, 0),
        Ds323x.AlarmType.WhenSecondsMatch);

    sensor.DisplayRegisters();

    return base.Run();
}

private void Sensor_OnAlarm1Raised(object sender)
{
    var rtc = (Ds3231)sender;
    Resolver.Log.Info("Alarm 1 has been activated: " + rtc.CurrentDateTime.ToString("dd MMM yyyy HH:mm:ss"));
    rtc.ClearInterrupt(Ds323x.Alarm.Alarm1Raised);
}

Sample project(s) available on GitHub

Wiring Example

The DS3231 real time clock module (see image below) requires only four (for simple timekeeping) or five (for alarms) connections

DS323x	Meadow Pin
VCC	3.3V
GND	GND
SCK	SC
SDA	SD
Interrupt	SQW

It should look like the following diagram:

The 32K pin outputs the 32,768 Hz clock signal from the module. This signal is only available when power is supplied by V_cc, it is not available when the module is on battery power.

The orange wire is only required if the alarms are being used to interrupt the Meadow.

Class Ds323x

Base class for DS323x family of real-time clocks

Assembly: Ds323x.dll

View Source

Declaration

public class Ds323x : PollingSensorBase<Temperature>, IObservable<IChangeResult<Temperature>>, ISamplingSensor<Temperature>, ISensor<Temperature>, ISensor, ISamplingSensor, IRealTimeClock, II2cPeripheral, IDisposable

Inheritance: System.Object -> Meadow.Foundation.ObservableBase<UNIT>

Derived:
Meadow.Foundation.RTCs.Ds3231

Implements:
System.IObservable<Meadow.IChangeResult<Meadow.Units.Temperature>>, Meadow.Peripherals.Sensors.ISamplingSensor<Meadow.Units.Temperature>, Meadow.Peripherals.Sensors.ISensor<Meadow.Units.Temperature>, Meadow.Peripherals.Sensors.ISensor, Meadow.Peripherals.Sensors.ISamplingSensor, Meadow.Hardware.IRealTimeClock, Meadow.Hardware.II2cPeripheral, System.IDisposable

Properties

DefaultI2cAddress

The default I2C address for the peripheral

View Source

Declaration

public byte DefaultI2cAddress { get; }

IsRunning

Stops or starts the clock oscillator

View Source

Declaration

public bool IsRunning { get; set; }

IsDisposed

Is the object disposed

View Source

Declaration

public bool IsDisposed { get; }

CurrentDateTime

Get / Set the current date and time.

View Source

Declaration

public DateTimeOffset CurrentDateTime { get; set; }

Temperature

Get the current die temperature.

View Source

Declaration

public Temperature Temperature { get; }

InterruptPort

Interrupt port attached to the DS323x RTC module.

View Source

Declaration

protected IDigitalInterruptPort? InterruptPort { get; }

ControlRegister

Control register.

View Source

Declaration

protected byte ControlRegister { get; set; }

ControlStatusRegister

Control and status register.

View Source

Declaration

protected byte ControlStatusRegister { get; set; }

WhichAlarm

Determine which alarm has been raised.

View Source

Declaration

protected Ds323x.Alarm WhichAlarm { get; }

Fields

i2cComms

I2C Communication bus used to communicate with the i2cComms

View Source

Declaration

protected II2cCommunications i2cComms

Methods

ReadSensor()

Read value from sensor

View Source

Declaration

protected override Task<Temperature> ReadSensor()

Returns

System.Threading.Tasks.Task<Meadow.Units.Temperature>: unitized value### GetTime() Reads the RTC time

View Source

Declaration

public DateTimeOffset GetTime()

Returns

System.DateTimeOffset

SetTime(DateTimeOffset)

Sets the RTC time

View Source

Declaration

public void SetTime(DateTimeOffset time)

Parameters

Type	Name
System.DateTimeOffset	time

DecodeDateTimeRegisters(Span<byte>)

Get the the date and time register contents

View Source

Declaration

protected DateTimeOffset DecodeDateTimeRegisters(Span<byte> data)

Returns

System.DateTimeOffset: DateTimeOffset object version of the data.

Parameters

Type	Name	Description
System.Span<System.Byte>	data	Register contents.

EncodeDateTimeRegisters(DateTimeOffset)

Encode the a DateTime object into the format used by the DS323x chips.

View Source

Declaration

protected byte[] EncodeDateTimeRegisters(DateTimeOffset dt)

Returns

System.Byte[]: Bytes to send to the DS323x chip.

Parameters

Type	Name	Description
System.DateTimeOffset	dt	DateTime object to encode.

DayOfWeekToByte(DayOfWeek)

Convert the day of the week to a byte.

View Source

Declaration

protected byte DayOfWeekToByte(DayOfWeek day)

Returns

System.Byte: Byte representation of the day of the week (Sunday = 1).

Parameters

Type	Name	Description
System.DayOfWeek	day	Day of the week

SetAlarm(Alarm, DateTimeOffset, AlarmType)

Set one of the two alarms on the DS323x module.

View Source

Declaration

public void SetAlarm(Ds323x.Alarm alarm, DateTimeOffset time, Ds323x.AlarmType type)

Parameters

Type	Name	Description
Meadow.Foundation.RTCs.Ds323x.Alarm	alarm	Define the alarm to be set.
System.DateTimeOffset	time	Date and time for the alarm.
Meadow.Foundation.RTCs.Ds323x.AlarmType	type	Type of alarm to set.

EnableDisableAlarm(Alarm, bool)

Enable or disable the specified alarm.

View Source

Declaration

public void EnableDisableAlarm(Ds323x.Alarm alarm, bool enable)

Parameters

Type	Name	Description
Meadow.Foundation.RTCs.Ds323x.Alarm	alarm	Alarm to enable / disable.
System.Boolean	enable	Alarm state, true = on, false = off.

ClearInterrupt(Alarm)

Clear the alarm interrupt flag for the specified alarm.

View Source

Declaration

public void ClearInterrupt(Ds323x.Alarm alarm)

Parameters

Type	Name	Description
Meadow.Foundation.RTCs.Ds323x.Alarm	alarm	Alarm to clear.

DisplayRegisters()

Display the registers.

View Source

Declaration

public void DisplayRegisters()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

View Source

Declaration

public void Dispose()

Dispose(bool)

Dispose of the object

View Source

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	Is disposing

Events

OnAlarm1Raised

Event raised when Alarm1 is triggered.

View Source

Declaration

public event Ds323x.AlarmRaised OnAlarm1Raised

Event Type

Meadow.Foundation.RTCs.Ds323x.AlarmRaised

OnAlarm2Raised

Event raised when Alarm2 is triggered.

View Source

Declaration

public event Ds323x.AlarmRaised OnAlarm2Raised

Event Type

Meadow.Foundation.RTCs.Ds323x.AlarmRaised

Implements

• System.IObservable<Meadow.IChangeResult<Meadow.Units.Temperature>>
• Meadow.Peripherals.Sensors.ISamplingSensor<Meadow.Units.Temperature>
• Meadow.Peripherals.Sensors.ISensor<Meadow.Units.Temperature>
• Meadow.Peripherals.Sensors.ISensor
• Meadow.Peripherals.Sensors.ISamplingSensor
• Meadow.Hardware.IRealTimeClock
• Meadow.Hardware.II2cPeripheral
• System.IDisposable