Desk clock on an Arduino Uno

// Desk clock: a DS3231 over I2C, the time on a four-digit TM1637.
//
//   A5 -> SCL   A4 -> SDA   the clock module carries its own pull-ups
//   pin 4 -> CLK   pin 5 -> DIO   the display's two wires
//
// Two two-wire devices on one board, and they are two *different* two-wire
// buses, which is the thing worth taking away from this circuit.
//
// # The clock speaks I2C
//
// Address 0x68, fixed; there is no address pin on a DS3231. Seven registers
// hold the time and they are read in **one** transfer, because reading them one
// at a time lets the clock tick between the minutes and the seconds, and
// 10:00:59 comes out as 10:01:59 once an hour for ever.
//
// Every one of those registers is binary coded decimal: two decimal digits, one
// per nibble, so twenty-five seconds is 0x25 and not 25. That is the whole of
// the DS3231 for most sketches and it is the one thing everybody gets wrong
// once. The driver converts both ways so nothing above it sees a BCD byte.
//
// # The display does not
//
// The TM1637's bus looks like I2C (same START, same STOP, an acknowledge on a
// ninth clock), and it is not, in two ways that break any attempt to drive it
// with a Wire library:
//
//   * there is no address, so the first byte is a command and the chip answers
//     everything on the wire;
//   * the bytes go least significant bit first, where I2C is most significant
//     first. Get that wrong and it lights a plausible set of wrong segments.
//
// # The colon
//
// It is bit 7 of the *second* digit and nowhere else. That is this module's
// wiring, not the chip's, which is why every library has a special case for it.
// Here it blinks once a second, which is what tells you the clock is running
// rather than the sketch having stopped with a number on the screen.
//
// # The oscillator-stop flag
//
// Bit 7 of the status register comes up set after power, and it means "this
// time cannot be trusted". A real module keeps time on its coin cell and clears
// it when it is set; Mokxi's part has no battery, so it powers up at whatever
// the `start` property says with the flag raised. The sketch prints it once,
// because on a real bench that flag is how you find out somebody's cell is
// flat.

#include "mokxi_ds3231.h"
#include "mokxi_i2c.h"
#include "mokxi_tm1637.h"

const int SCL_PIN = A5;
const int SDA_PIN = A4;
const int TM_CLK = 4;
const int TM_DIO = 5;

SoftI2c bus(SCL_PIN, SDA_PIN);
Ds3231 rtc(bus);
Tm1637 panel(TM_CLK, TM_DIO);

unsigned char digits[4];
int lastSecond = -1;

// Two digits with the leading zero, which is what a clock wants everywhere.
void print2(int value) {
  if (value < 10) {
    Serial.print("0");
  }
  Serial.print(value);
}

void setup() {
  Serial.begin(115200);
  Serial.println("Mokxi Uno: DS3231 desk clock on a TM1637");
  bus.begin();
  panel.begin();

  if (!rtc.begin()) {
    Serial.println("nothing answered at 0x68");
    return;
  }
  unsigned char status = rtc.status();
  Serial.print("status 0x");
  Serial.print((long)status, HEX);
  Serial.println((status & DS3231_OSF) ? "  (OSF set: the time is a guess)" : "  (time trusted)");

  // Alarm 1 on the zeroth second of every minute, so the sketch has something
  // to notice besides the digits changing.
  rtc.setAlarm1Seconds(0);
  rtc.writeControl(DS3231_INTCN | DS3231_A1IE);
  rtc.alarmFired(DS3231_A1F);
}

void loop() {
  Ds3231Time now;
  if (!rtc.now(now)) {
    Serial.println("read failed");
    delay(500);
    return;
  }

  if ((int)now.seconds != lastSecond) {
    lastSecond = (int)now.seconds;
    Tm1637::clock(now.hours, now.minutes, digits);
    // The colon blinks on the even second, which is how you can see it running.
    Tm1637::setColon(digits, (now.seconds % 2) == 0);
    panel.show(digits, 5);

    if (now.seconds == 0) {
      Serial.print(now.year);
      Serial.print("-");
      print2((int)now.month);
      Serial.print("-");
      print2((int)now.date);
      Serial.print(" ");
      print2((int)now.hours);
      Serial.print(":");
      print2((int)now.minutes);
      Serial.print(":");
      print2((int)now.seconds);
      Serial.print("  chip ");
      Serial.print(rtc.temperatureQuarters() / 4);
      Serial.print(" C");
      Serial.println(rtc.alarmFired(DS3231_A1F) ? "  [alarm 1]" : "");
    }
  }
  delay(50);
}