chronos-esp32 Library

chronos-esp32 is a wrapper library for the ESP32 designed to facilitate the development of smartwatch-like projects. It enables an ESP32 device to act as a smartwatch by connecting to the Chronos companion app via Bluetooth Low Energy (BLE).

Key capabilities include:

• Time Sync: Automatic time synchronization via BLE.
• Notifications: Receiving notifications from the connected smartphone.
• Weather: Receiving weather information.
• Controls: Controlling music, finding the phone, and controlling the camera.
• Phone Status: Monitoring phone battery level and charging state (requires Chronos app v3.5.1+).
• Navigation: Navigation support (requires Chronos app v3.7.5+).
• Additional Features: Support for contacts and QR codes.

To ensure the ChronosESP32 library functions correctly, follow these operational requirements:

• Initialization Order: Call setName() and setScreen() before calling begin().
• Callbacks: Register any callbacks before calling begin().
• Main Loop: You must continuously call watch.loop(). This is critical as several outgoing updates and timeouts depend on it.
• Address Retrieval: The getAddress() method is only populated after begin() has been called.
• Data Storage: The library stores notifications, weather, alarms, contacts, QR links, and navigation state in RAM.
• Index Safety: Several indexed getters use modulo arithmetic, meaning out-of-range indices will not cause a failure.
• Disconnection Behavior: When a disconnect occurs, advertising restarts and the camera state is reset to inactive.

To use ChronosESP32, include the header and instantiate a ChronosESP32 object. You must call begin() in your setup() function and loop() in your main loop. You can also set callbacks for connections, notifications, and configuration updates.

Important Pairing Note: Do not pair the device via phone Bluetooth settings. Instead, use the Chronos companion app: Chronos app > Watches tab > Watches button > Pair New Devices > Search > select your board.

#include <ChronosESP32.h>

ChronosESP32 watch;

void setup() {
  Serial.begin(115200);

  // Optional: Set callbacks
  watch.setConnectionCallback(connectionCallback);
  watch.setNotificationCallback(notificationCallback);
  watch.setConfigurationCallback(configCallback);

  watch.begin();
  watch.setBattery(80);
}

void loop() {
  watch.loop();
}

The default notification ring buffer size is defined by CS_NOTIF_SIZE (default: 10). You can override this by defining the constant before including the header, or by using a PlatformIO build flag.

Using C++ define:

#define CS_NOTIF_SIZE 20
#include <ChronosESP32.h>

Using PlatformIO (platformio.ini):

build_flags = -D CS_NOTIF_SIZE=20

Weather data is provided via specific getter methods. Indices wrap around based on defined buffer sizes (CS_WEATHER_SIZE and CS_FORECAST_SIZE).

• getWeatherCount(): Returns the number of weather items.
• getWeatherAt(int index): Returns a Weather object.
• getForecastHour(int hour): Returns an HourlyForecast object for the specified hour.
• getWeatherLocation(): Returns the current WeatherLocation.
• getWeatherCity() / getWeatherTime(): Returns the city name and time string.

The ChronosESP32 class is the primary interface for the library. Use the constructor to set the device name and screen type, then call begin() to start operations.

Key Lifecycle Methods:

• begin(): Starts the library. Call setName() and setScreen() before this.
• loop(): Must be called continuously in your main loop. It handles internal tasks like delayed info sync, battery sync, and find-phone timeouts.
• stop(bool clearAll): Stops the library and deinitializes the BLE device. If clearAll is true, it clears all resources.
• setChunkedTransfer(bool chunked): Enables splitting outgoing packets larger than 20 bytes. This is useful if the companion app is configured for chunked transfers.

ChronosESP32 chronos("MyWatch", CF_ESP32_240x240);

void setup() {
  chronos.begin();
}

void loop() {
  chronos.loop();
}

You can send both real-time and historical health data to the companion app. Real-time methods should typically be called in response to setHealthRequestCallback().

Real-time Methods:

• sendRealtimeSteps(uint32_t steps, uint32_t calories)
• sendRealtimeHeartRate(uint8_t heartRate)
• sendRealtimeBloodPressure(uint8_t systolic, uint8_t diastolic)
• sendRealtimeBloodOxygen(uint8_t bloodOxygen)
• sendRealtimeHealthData(uint8_t heartRate, uint8_t bloodOxygen, uint8_t systolic, uint8_t diastolic)

Historical Records (using DateTime or individual components):

• sendStepsRecord(...)
• sendHeartRateRecord(...)
• sendBloodPressureRecord(...)
• sendBloodOxygenRecord(...)
• sendSleepRecord(...)
• sendTemperatureRecord(...)

Notifications are stored in a ring buffer of size CS_NOTIF_SIZE. Use getNotificationAt(index) to retrieve a notification. Index 0 returns the most recent notification.

Notification Structure:

• int icon: Icon identifier
• String app: Source application name
• String time: Timestamp string
• String title: Notification title
• String message: Notification body text

Notifications are stored in a buffer. Index 0 represents the latest notification.

• getNotificationCount(): Returns the number of pending notifications.
• getNotificationAt(int index): Retrieves the Notification object at the specified index.
• clearNotifications(): Resets the count to zero. Note that old buffer data remains until overwritten.