DS3231 I2C

Github Repo	C Header	C source	JS source
mongoose-os-libs/ds3231	mgos_ds3231.h		api_ds3231.js

Implementation

The library implements 2 structures: struct mgos_ds3231 and a helper struct mgos_ds3231_date_time. Both structures are available for mJS too. The mJS support is available if the user includes the mjs library:

  - origin: https://github.com/mongoose-os-libs/mjs

struct mgos_ds3231

This is used to communicate with the DS3231. The RTC data is read into and written from using the helper struct mgos_ds3231_date_time

Example in C

struct mgos_ds3231* ds=mgos_ds3231_create(addr);
time_t unixtime=time(NULL);
mgos_ds3231_write_unixtime(ds, unixtime);
mgos_ds3231_free(ds);

Example in mJS

let ds=DS3231.create(addr);
let unixtime=Timer.now();
ds.writeUnixtime(unixtime);
ds.free();

struct mgos_ds3231_date_time

Encapsulates the DS3231 date/time information plus the unix timestamp. Several functions are provided to create and free the structure and to get/set different fields.

Example in C

struct mgos_ds3231_date_time* dt=mgos_ds3231_date_time_create();
mgos_ds3231_date_time_set_date(dt, 2016, 2, 3);
// mgos_ds3231_date_time_set_time will calculate the unixtime.
// It is VERY important to call mgos_ds3231_date_time_set_date first
mgos_ds3231_date_time_set_time(dt, 12, 34, 56);

struct mgos_ds3231* ds=mgos_ds3231_create(addr);
mgos_ds3231_write(ds, dt);
mgos_ds3231_settimeofday(ds);

mgos_ds3231_free(ds);
mgos_ds3231_date_time_free(dt);

Example in mJS

let dt=DS3231DateTime.create();
dt.setDate(2016, 2, 3);
dt.setTime(12, 34, 56);

let ds=DS3231.create(addr);
ds.write(dt);
ds.setTimeOfDay();

ds.free();
dt.free();

---

mgos_ds3231_date_time_create

struct mgos_ds3231_date_time *mgos_ds3231_date_time_create();

Create a mgos_ds3231_date_time structure

mgos_ds3231_date_time_free

void mgos_ds3231_date_time_free(struct mgos_ds3231_date_time *dt);

Free the mgos_ds3231_date_time structure

mgos_ds3231_date_time_set_date

void mgos_ds3231_date_time_set_date(struct mgos_ds3231_date_time *dt,
                                    uint16_t year, uint8_t month, uint8_t day);

Set the date part of the mgos_ds3231_date_time structure. The Dow member is computed by the function

mgos_ds3231_date_time_set_time

void mgos_ds3231_date_time_set_time(struct mgos_ds3231_date_time *dt,
                                    uint8_t hour, uint8_t minute,
                                    uint8_t second);

Set the time part of the mgos_ds3231_date_time structure. The unixtime member is set by this function. The day/time MUST be UTC mgos_ds3231_date_time_set_date should be called before.

mgos_ds3231_date_time_get_unixtime

time_t mgos_ds3231_date_time_get_unixtime(
    const struct mgos_ds3231_date_time *dt);

Get the unixtime time part of the mgos_ds3231_date_time structure.

mgos_ds3231_date_time_set_unixtime

void mgos_ds3231_date_time_set_unixtime(struct mgos_ds3231_date_time *dt,
                                        time_t unixtime);

Set the members of struct mgos_ds3231_date_time from the provided unixtime

mgos_ds3231_date_time_get_year

uint16_t mgos_ds3231_date_time_get_year(struct mgos_ds3231_date_time *dt);

mgos_ds3231_create

struct mgos_ds3231 *mgos_ds3231_create(uint8_t addr);

Create a struct mgos_ds3231 structure

mgos_ds3231_free

void mgos_ds3231_free(struct mgos_ds3231 *ds);

Free a struct mgos_ds3231 structure

mgos_ds3231_read

const struct mgos_ds3231_date_time *mgos_ds3231_read(struct mgos_ds3231 *ds);

Read the current date and time, returning a structure containing that information.

mgos_ds3231_write

bool mgos_ds3231_write(struct mgos_ds3231 *ds,
                       const struct mgos_ds3231_date_time *date);

Set the date and time from the settings in the given structure.

mgos_ds3231_write_unixtime

bool mgos_ds3231_write_unixtime(struct mgos_ds3231 *ds, const time_t unixtime);

Set the date and time from unixtime.

mgos_ds3231_settimeofday

int mgos_ds3231_settimeofday(struct mgos_ds3231 *ds);

Sets the system time from the DS3231 data. Assumes DS3231 was previously setup with correct data.

Returns 0 if success.

mgos_ds3231_get_temperature_c

float mgos_ds3231_get_temperature_c(struct mgos_ds3231 *ds);

Get the temperature accurate to within 0.25 Celsius

mgos_ds3231_get_temperature_f

float mgos_ds3231_get_temperature_f(struct mgos_ds3231 *ds);

Get the temperature in Fahrenheit

mgos_ds3231_disable_alarms

bool mgos_ds3231_disable_alarms(struct mgos_ds3231 *ds);

• Disable any existing alarm settings.

@return Success True/False

mgos_ds3231_check_alarms

uint8_t mgos_ds3231_check_alarms(struct mgos_ds3231 *ds);

Determine if an alarm has triggered, also clears the alarm if so.

Returns 0 for no alarm, 1 for Alarm 1, 2 for Alarm 2, and 3 for both alarms

mgos_ds3231_check_stopflag

uint8_t mgos_ds3231_check_stopflag(struct mgos_ds3231 *ds, int clear);

Determine if the oscillator stop flag is set

Returns the flag status

mgos_ds3231_set_alarm

uint8_t mgos_ds3231_set_alarm(struct mgos_ds3231 *ds,
                              const struct mgos_ds3231_date_time *alarm_date,
                              uint8_t alarm_mode);

Sets an alarm, the alarm will pull the SQW pin low (you can monitor with an interrupt).

alarm_date The date/time for the alarm, as appropriate for the alarm mode (example, for ALARM_MATCH_SECOND then alarm_date.Second will be the matching criteria).

alarm_mode the mode of the alarm, from the following...

MGOS_DS3231_ALARM_EVERY_SECOND MGOS_DS3231_ALARM_MATCH_SECOND MGOS_DS3231_ALARM_MATCH_SECOND_MINUTE MGOS_DS3231_ALARM_MATCH_SECOND_MINUTE_HOUR MGOS_DS3231_ALARM_MATCH_SECOND_MINUTE_HOUR_DATE MGOS_DS3231_ALARM_MATCH_SECOND_MINUTE_HOUR_DOW

MGOS_DS3231_ALARM_EVERY_MINUTE MGOS_DS3231_ALARM_MATCH_MINUTE MGOS_DS3231_ALARM_MATCH_MINUTE_HOUR MGOS_DS3231_ALARM_MATCH_MINUTE_HOUR_DATE MGOS_DS3231_ALARM_MATCH_MINUTE_HOUR_DOW

MGOS_DS3231_ALARM_HOURLY MGOS_DS3231_ALARM_DAILY MGOS_DS3231_ALARM_WEEKLY MGOS_DS3231_ALARM_MONTHLY

JS API

---

DS3231DateTime.create

DS3231DateTime.create()

Creates a DS3231DateTime instance to be used for reading/wrtting data from/to DS3231. Return value: an object with the methods described below.

dsData.free

dsData.free()

Frees a DS3231DateTime instance. No methods can be called on this instance after that. Return value: none.

DS3231.createI2C

DS3231.createI2C(address)

Creates a DS3231 instance on the I2C bus with the given address address. Return value: an object with the methods described below.

rtc.free

rtc.free()

Frees the DS3231 instance. No methods can be called on this instance after that. Return value: none.

rtc.read

rtc.read()

Reads date/time from the RTC Returns a DS3231DateTime struct.

rtc.write

rtc.write(dt)

Writes a DS3231DateTime structure Returns true on success

rtc.writeUnixtime

rtc.writeUnixtime(unixtime)

Sets the date/time from a unixtime Returns true on success

rtc.getTemperatureC

rtc.getTemperatureC()

Return the temperature in Celsius

rtc.getTemperatureF

rtc.getTemperatureF()

Return the temperature in Fahrenheit

rtc.disableAlarms

rtc.disableAlarms()

Disable alarms Returns true on success

rtc.checkAlarms

rtc.checkAlarms()

Disable alarms Returns: 0 if no alarm 1 if Alarm1 was triggered 2 if Alarm2 was triggered 3 if both alarms were triggered

rtc.checkStopFlag

rtc.checkStopFlag()

Check the OSF bit Returns: the oscillator stop flag bit

rtc.setAlarm

rtc.setAlarm(alarm)

Set alarm dt - a DS3231DateTime structure mode - an alarm mode selected from the ALARM_ constants Returns true on success

rtc.setTimeOfDay

rtc.setTimeOfDay()

Set system time Returns 0 on success

edit this doc