Remarks

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.

Characteristic	Locus
Inheritance	System.Object > Ds323x > Ds3231
Namespace	Meadow.Foundation.RTCs
Assembly	Ds323x.dll

Syntax

public class Ds323x : IDisposable

Constructors

Ds323x(I2cPeripheral, IDigitalInputPort)

Create a new Ds323x object

Declaration

protected Ds323x(I2cPeripheral peripheral, IDigitalInputPort interruptPort)

Parameters

Type	Name	Description
I2cPeripheral	peripheral
IDigitalInputPort	interruptPort

Ds323x(I2cPeripheral, IPin)

Create a new Ds323x object

Declaration

protected Ds323x(I2cPeripheral peripheral, IPin interruptPin)

Parameters

Type	Name	Description
I2cPeripheral	peripheral
IPin	interruptPin

Properties

ControlRegister

Control register.

Declaration

protected byte ControlRegister { get; set; }

Property Value

Type	Description
System.Byte

Remarks

Control register contains the following bit (in sequence b7 - b0): EOSC - BBSQW - CONV - RS1 - RS2 - INTCN - A2IE - A1IE

ControlStatusRegister

Control and status register.

Declaration

protected byte ControlStatusRegister { get; set; }

Property Value

Type	Description
System.Byte

Remarks

Control and status register contains the following bit (in sequence b7 - b0): OSF - 0 - 0 - 0 - EN32KHZ - BSY - A2F - A1F

CurrentDateTime

Get / Set the current date and time.

Declaration

public DateTime CurrentDateTime { get; set; }

Property Value

Type	Description
DateTime

ds323x

DS323x Real Time Clock object.

Declaration

protected II2cPeripheral ds323x { get; }

Property Value

Type	Description
II2cPeripheral

InterruptPort

Interrupt port attached to the DS323x RTC module.

Declaration

protected IDigitalInputPort InterruptPort { get; }

Property Value

Type	Description
IDigitalInputPort

Temperature

Get the current die temperature.

Declaration

public Units.Temperature Temperature { get; }

Property Value

Type	Description
Units.Temperature

WhichAlarm

Determine which alarm has been raised.

Declaration

protected Ds323x.Alarm WhichAlarm { get; }

Property Value

Type	Description
Ds323x.Alarm

Methods

ClearInterrupt(Ds323x.Alarm)

Clear the alarm interrupt flag for the specified alarm.

Declaration

public void ClearInterrupt(Ds323x.Alarm alarm)

Parameters

Type	Name	Description
Ds323x.Alarm	alarm	Alarm to clear.

DayOfWeekToByte(DayOfWeek)

Convert the day of the week to a byte.

Declaration

protected byte DayOfWeekToByte(DayOfWeek day)

Parameters

Type	Name	Description
DayOfWeek	day	Day of the week

Returns

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

DecodeDateTimeRegisters(Span<Byte>)

Decode the register contents and create a DateTime version of the register contents.

Declaration

protected DateTime DecodeDateTimeRegisters(Span<byte> data)

Parameters

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

Returns

Type	Description
DateTime	DateTime object version of the data.

DisplayRegisters()

Display the registers.

Declaration

public void DisplayRegisters()

Dispose()

Dispose

Declaration

public void Dispose()

EnableDisableAlarm(Ds323x.Alarm, Boolean)

Enable or disable the specified alarm.

Declaration

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

Parameters

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

EncodeDateTimeRegisters(DateTime)

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

Declaration

protected byte[] EncodeDateTimeRegisters(DateTime dt)

Parameters

Type	Name	Description
DateTime	dt	DateTime object to encode.

Returns

Type	Description
System.Byte[]	Bytes to send to the DS323x chip.

SetAlarm(Ds323x.Alarm, DateTime, Ds323x.AlarmType)

Set one of the two alarms on the DS323x module.

Declaration

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

Parameters

Type	Name	Description
Ds323x.Alarm	alarm	Define the alarm to be set.
DateTime	time	Date and time for the alarm.
Ds323x.AlarmType	type	Type of alarm to set.

Events

OnAlarm1Raised

Event raised when Alarm1 is triggered.

Declaration

public event Ds323x.AlarmRaised OnAlarm1Raised

Event Type

Type	Description
Ds323x.AlarmRaised

OnAlarm2Raised

Event raised when Alarm2 is triggered.

Declaration

public event Ds323x.AlarmRaised OnAlarm2Raised

Event Type

Type	Description
Ds323x.AlarmRaised