tiny_cts::TinyCTSClient Class Reference

Reads the time from a BLE device that offers the Current Time Service (a phone, a watch, a TinyCTSServer, ...). It is also a TinyCTSTimeSource. More...

#include <TinyCTSClientDesktop.h>

Inheritance diagram for tiny_cts::TinyCTSClient:

Public Member Functions
	TinyCTSClient (const char *device=nullptr, uint32_t scanMs=5000)
	TinyCTSClient (const char *device=nullptr, uint32_t scanMs=5000)
	TinyCTSClient (const char *device=nullptr, uint32_t scanMs=5000)
	TinyCTSClient (const char *device=nullptr, uint32_t scanMs=5000)
bool	begin ()
	Find the device and read the time.
bool	begin ()
	Start the BLE hardware, find the device and read the time.
bool	begin ()
	Find the device and read the time. NimBLEDevice::init() is called, if the NimBLE stack is not initialized yet.
bool	begin ()
	Start the BLE hardware, find the device and read the time.
const std::string &	getLastError () const
	The reason why the last call failed.
uint32_t	getRoundTripMs () const
	The round trip time of the last read or write in ms (the connection interval).
std::vector< TinyCTSScanEntry >	scan (uint32_t timeoutMs)
	List the devices that are in range.
void	setAdapter (const char *name)
	The Bluetooth adapter to use (Linux only, default: hci0).
bool	setTimeMs (uint64_t unixMs) override
	Set the time of the device by writing the Current Time. It works if the device allows it; if it requires an encrypted connection, pair it first.
bool	setTimeMs (uint64_t unixMs) override
	Set the time of the device by writing the Current Time. It works if the device allows it (and the connection is paired, if it requires it).
bool	setTimeMs (uint64_t unixMs) override
	Set the time of the device by writing the Current Time. It works if the device allows it (and the connection is paired, if it requires it).
bool	setTimeMs (uint64_t unixMs) override
	Set the time of the device by writing the Current Time. It works if the device allows it (and the connection is paired, if it requires it).
bool	setTimeZone (const TinyCTSLocalTimeInfo &info)
	Set the time zone of the device by writing its Local Time Information (if the device allows it).
bool	update ()
	Read the time (and the other characteristics) again: the device is connected, read and disconnected.
bool	update ()
	Read the time (and the other characteristics) again: the device is connected, read and disconnected.
bool	update ()
	Read the time (and the other characteristics) again: the device is connected, read and disconnected.
bool	update ()
	Read the time (and the other characteristics) again: the device is connected, read and disconnected.
Public Member Functions inherited from tiny_cts::TinyCTSClientBase
const TinyCTSCurrentTime &	getCurrentTime () const
	The Current Time as it was sent by the device.
const std::string &	getDeviceAddress () const
	The address of the device that was used.
const std::string &	getDeviceName () const
	The name of the device that was used (empty before begin()).
const TinyCTSLocalTimeInfo &	getLocalTimeInfo () const
	The time zone of the device (valid after update() if it has it).
std::tm	getLocalTm ()
	The local time as std::tm, with the offsets of the device.
const TinyCTSReferenceTimeInfo &	getReferenceTimeInfo () const
	Where the time of the device comes from.
uint32_t	getTime ()
	The UTC time in seconds since 1970-01-01 (0 if not known).
uint64_t	getTimeMs () override
	The UTC time in ms since 1970-01-01, extrapolated since the last update.
std::tm	getTm ()
	The UTC time as std::tm.
void	setLocalTimeInfo (const TinyCTSLocalTimeInfo &info)
	Tell the client the time zone of the device, if it does not have the Local Time Information. Used for the local time and, with setTimeIsLocal(), when the time is set.
void	setTimeIsLocal (bool local)
	The Current Time of the device is the local time, not UTC.

Protected Member Functions
TinyCTSCentral *	central ()
bool	connect ()
NimBLEClient *	connect ()
BLEClient *	connect ()
bool	connect (BLEDevice &peripheral)
void	readInfo (NimBLERemoteService *service)
Protected Member Functions inherited from tiny_cts::TinyCTSClientBase
bool	isWanted (const std::string &address, const std::string &name) const
bool	storeCurrentTime (const uint8_t *data, size_t len, uint32_t startMs, uint32_t endMs)
void	storeLocalInfo (const uint8_t *data, size_t len)
void	storeReferenceInfo (const uint8_t *data, size_t len)
size_t	timeToWrite (uint64_t unixMs, uint8_t *out) const

Static Protected Member Functions
static bool	offersService (BLEDevice &d)
	true if the device is advertising the Current Time Service
static bool	read (BLEDevice &peripheral, const char *uuid, uint8_t *out, size_t &len)
static bool	read (BLERemoteCharacteristic *chr, uint8_t *out, size_t &len)
static void	release (NimBLEClient *client)
Static Protected Member Functions inherited from tiny_cts::TinyCTSClientBase
static bool	equalsIgnoreCase (const std::string &a, const std::string &b)

Protected Attributes
std::string	_adapterName = "hci0"
std::unique_ptr< TinyCTSCentral >	_central
std::string	_error
uint32_t	_roundTripMs = 0
uint32_t	_scanMs
Protected Attributes inherited from tiny_cts::TinyCTSClientBase
std::string	_address
TinyCTSCurrentTime	_current
std::string	_device
TinyCTSLocalTimeInfo	_info
uint32_t	_lastMillis = 0
std::string	_name
TinyCTSReferenceTimeInfo	_ref
bool	_timeIsLocal = false
uint64_t	_timeMs = 0

Detailed Description

Reads the time from a BLE device that offers the Current Time Service (a phone, a watch, a TinyCTSServer, ...). It is also a TinyCTSTimeSource.

Reads the time from a BLE device that offers the Current Time Service (a phone, a watch, a TinyCTSServer, ...). It is also a TinyCTSTimeSource, so the time can be served by a TinyCTSServer.

This is the version for the desktop. The functions block until they are done. begin() scans for the device, connects, reads the characteristics and disconnects: the time is then extrapolated with the clock of the computer. The getters are in TinyCTSClientBase.

TinyCTSClient cts;
if (cts.begin()) printf("%llu\n", (unsigned long long)cts.getTimeMs());
else fprintf(stderr, "%s\n", cts.getLastError().c_str());

begin() starts the BLE hardware (BLE.begin()), scans for the device, connects, reads the characteristics and disconnects: the time is then extrapolated with millis(). Call update() from time to time (e.g. once per hour) to stay in sync. The functions block until they are done. The getters are in TinyCTSClientBase.

TinyCTSClient cts;
void setup() {
  if (cts.begin()) Serial.println((uint32_t)cts.getTime());
}

begin() scans for the device, connects, reads the characteristics and disconnects: the time is then extrapolated with millis(). Call update() from time to time (e.g. once per hour) to stay in sync. The getters are in TinyCTSClientBase.

TinyCTSClient cts;
void setup() {
  if (cts.begin()) Serial.println(cts.getTimeMs());
}

Select "Tools -> IP/Bluetooth Stack -> IPv4 + Bluetooth". begin() starts the BLE hardware (do not call BLE.begin() yourself), scans for the device, connects, reads the characteristics and disconnects: the time is then extrapolated with millis(). Call update() from time to time (e.g. once per hour) to stay in sync. The functions block until they are done. The getters are in TinyCTSClientBase.

TinyCTSClient cts;
void setup() {
  if (cts.begin()) Serial.println((uint32_t)cts.getTime());
}

Constructor & Destructor Documentation

TinyCTSClient() [1/4]

tiny_cts::TinyCTSClient::TinyCTSClient ( const char * device = nullptr, uint32_t scanMs = 5000 )

inlineexplicit

Parameters

device	The Bluetooth address ("AA:BB:CC:DD:EE:FF") or the name of the device (macOS: the identifier that CoreBluetooth has assigned instead of the address). nullptr (default): the first device that advertises the service.
scanMs	Time to look for the device.

TinyCTSClient() [2/4]

tiny_cts::TinyCTSClient::TinyCTSClient ( const char * device = nullptr, uint32_t scanMs = 5000 )

inlineexplicit

Parameters

device	The BLE address ("aa:bb:cc:dd:ee:ff") or the name of the device. nullptr (default): the first device that offers the service.
scanMs	Time to look for the device.

TinyCTSClient() [3/4]

tiny_cts::TinyCTSClient::TinyCTSClient ( const char * device = nullptr, uint32_t scanMs = 5000 )

inlineexplicit

Parameters

device	The BLE address ("aa:bb:cc:dd:ee:ff") or the name of the device. nullptr (default): the first device that offers the service.
scanMs	Time to look for the device.

TinyCTSClient() [4/4]

tiny_cts::TinyCTSClient::TinyCTSClient ( const char * device = nullptr, uint32_t scanMs = 5000 )

inlineexplicit

Parameters

device	The BLE address ("aa:bb:cc:dd:ee:ff") or the name of the device. nullptr (default): the first device that offers the service.
scanMs	Time to look for the device (rounded up to seconds).

Member Function Documentation

begin() [1/4]

bool tiny_cts::TinyCTSClient::begin ( )

inline

Find the device and read the time.

Returns

true on success.

begin() [2/4]

bool tiny_cts::TinyCTSClient::begin ( )

inline

Start the BLE hardware, find the device and read the time.

Returns

true if the time was read.

begin() [3/4]

bool tiny_cts::TinyCTSClient::begin ( )

inline

Find the device and read the time. NimBLEDevice::init() is called, if the NimBLE stack is not initialized yet.

Returns

true if the time was read.

begin() [4/4]

bool tiny_cts::TinyCTSClient::begin ( )

inline

Start the BLE hardware, find the device and read the time.

Returns

true if the time was read.

read()

bool tiny_cts::TinyCTSClient::read ( BLERemoteCharacteristic * chr, uint8_t * out, size_t & len )

inlinestaticprotected

Reads the value from the device (the get...() functions of the stack read it first) and copies it.

release()

void tiny_cts::TinyCTSClient::release ( NimBLEClient * client )

inlinestaticprotected

Disconnect and free the client: a new one is created for each use.

scan()

std::vector< TinyCTSScanEntry > tiny_cts::TinyCTSClient::scan ( uint32_t timeoutMs )

inline

List the devices that are in range.

Parameters

timeoutMs

How long to scan.

setTimeMs() [1/4]

bool tiny_cts::TinyCTSClient::setTimeMs ( uint64_t unixMs )

inlineoverridevirtual

Set the time of the device by writing the Current Time. It works if the device allows it; if it requires an encrypted connection, pair it first.

The time is the one at the moment of the call: the time that the connection needs and half of the round trip time of the write are added.

Parameters

unixMs

The UTC time in ms since 1970-01-01.

Reimplemented from tiny_cts::TinyCTSTimeSource.

setTimeMs() [2/4]

bool tiny_cts::TinyCTSClient::setTimeMs ( uint64_t unixMs )

inlineoverridevirtual

Set the time of the device by writing the Current Time. It works if the device allows it (and the connection is paired, if it requires it).

Parameters

unixMs

The UTC time in ms since 1970-01-01.

Reimplemented from tiny_cts::TinyCTSTimeSource.

setTimeMs() [3/4]

bool tiny_cts::TinyCTSClient::setTimeMs ( uint64_t unixMs )

inlineoverridevirtual

Set the time of the device by writing the Current Time. It works if the device allows it (and the connection is paired, if it requires it).

Parameters

unixMs

The UTC time in ms since 1970-01-01.

Reimplemented from tiny_cts::TinyCTSTimeSource.

setTimeMs() [4/4]

bool tiny_cts::TinyCTSClient::setTimeMs ( uint64_t unixMs )

inlineoverridevirtual

Set the time of the device by writing the Current Time. It works if the device allows it (and the connection is paired, if it requires it).

Parameters

unixMs

The UTC time in ms since 1970-01-01.

Reimplemented from tiny_cts::TinyCTSTimeSource.

update() [1/4]

bool tiny_cts::TinyCTSClient::update ( )

inline

Read the time (and the other characteristics) again: the device is connected, read and disconnected.

Returns

true if the time was read. The reason is in getLastError().

update() [2/4]

bool tiny_cts::TinyCTSClient::update ( )

inline

Read the time (and the other characteristics) again: the device is connected, read and disconnected.

Returns

true if the time was read.

update() [3/4]

bool tiny_cts::TinyCTSClient::update ( )

inline

Read the time (and the other characteristics) again: the device is connected, read and disconnected.

Returns

true if the time was read.

update() [4/4]

bool tiny_cts::TinyCTSClient::update ( )

inline

Read the time (and the other characteristics) again: the device is connected, read and disconnected.

Returns

true if the time was read.

---

The documentation for this class was generated from the following files:

• src/TinyCTS/desktop/TinyCTSClientDesktop.h
• src/TinyCTS/mcu/TinyCTSClientArduinoBLE.h
• src/TinyCTS/mcu/TinyCTSClientNimBLE.h
• src/TinyCTS/mcu/TinyCTSClientPico.h