The generic device interface. More...

#include <grmcdorman/device/Device.h>

Inheritance diagram for grmcdorman::device::Device:

Classes
class	Definition
	A sensor definition to be published to MQTT. More...

Public Types
typedef std::vector< const Definition * >	definition_list_t
	The type containing a list of Definition objects.

Public Member Functions
	Device (const __FlashStringHelper device_name, const __FlashStringHelper device_identifier)
	Construct a new Device object. More...

virtual	~Device ()
	Destroy the Device object.

const __FlashStringHelper *	name () const
	Get the device name; used for UI names and IDs. More...

virtual const __FlashStringHelper *	identifier () const
	Get the device identifier. More...

virtual void	set_defaults ()
	Set defaults, if necessary. More...

virtual void	set_devices (const std::vector< Device * > &list)
	For devices that support it, add devices to manage. More...

virtual void	setup ()=0
	Setup the device. More...

virtual void	loop ()=0
	Main loop. More...

virtual bool	publish (DynamicJsonDocument &json) const
	Publish the value and attributes. More...

virtual DynamicJsonDocument	as_json () const
	Get the values, as a JSON document. More...

const definition_list_t &	get_definitions () const
	Get the definitions list. More...

const ::grmcdorman::SettingInterface::settings_list_t &	get_settings () const
	Get the settings list. More...

bool	is_enabled () const
	Get whether this device is enabled. More...

void	set_enabled (bool state)
	Set whether this device is enabled. More...

void	set (const String &setting, const String &value)
	If possible, set a setting's value. More...

String	get (const String &setting) const
	Get a setting value, as a string. More...

virtual String	get_status () const
	Get a status report. More...

virtual bool	get_is_published () const
	Get whether the device readings have been published. More...

void	set_is_published ()
	Set the device as having published readings. More...

void	clear_is_published ()
	Set the device as not having published readings.

Static Public Member Functions
static void	set_system_identifiers (const __FlashStringHelper *firmware_name_value, const String &system_identifier_value=String())
	Set the system identifier values. More...

static const __FlashStringHelper *	get_firmware_name ()
	Get the firmware prefix. More...

static const String &	get_system_identifier ()
	Get the system identifier. More...

Static Public Attributes
static constexpr int	D0 = 16
	D0 is GPIO16, HIGH at boot, not suitable for most usages.

static constexpr int	D1 = 5
	D1 is GPIO5; often used as SCL.

static constexpr int	D2 = 4
	D2 is GPIO4; often used as SDA.

static constexpr int	D3 = 0
	D3 is GPIO0; pulled up; connected to FLASH button; not for input.

static constexpr int	D4 = 2
	D4 is GPIO2; pulled up; HIGH at boot; on-board LED; not for input.

static constexpr int	D5 = 14
	D5 is GPIO14; SPI (SCLK)

static constexpr int	D6 = 12
	D6 is GPIO12; SPI (MISO)

static constexpr int	D7 = 13
	D7 is GPIO13; SPI (MOSI)

static constexpr int	D8 = 15
	D8 is GPIO15; pulled to GND; SPI (CS); not recommended.

static const ExclusiveOptionSetting::names_list_t	data_line_names { FPSTR("D1"), FPSTR("D2"), FPSTR("D3"), FPSTR("D5"), FPSTR("D6"), FPSTR("D7")}
	Names for each configurable data line; see `settingsMap`.

Protected Member Functions
void	initialize (definition_list_t &&definition_list, ::grmcdorman::SettingInterface::settings_list_t &&setting_list)
	Initialize the definition and setting lists. More...

Static Protected Member Functions
static int	index_to_dataline (int index)
	Convert a data line index to a ESP data line. More...

static int	dataline_to_index (int dataLine)
	Convert a data line to an index. More...

Protected Attributes
ToggleSetting	enabled
	Whether this device is enabled.

Static Protected Attributes
static const int	settingsMap [6]
	The set of data lines usable for communication. More...

Detailed Description

The generic device interface.

A Device, generally, is something that needs to perform non-blocking operations in the main system loop, and can optionally publish to MQTT.

The device contains zero or more Descriptions, which are the individual sensors published to MQTT. It also contains zero or more Settings from the esp8266_web_settings library; these provide descriptions, configuration inputs, and status outputs.

Constructor & Destructor Documentation

◆ Device()

grmcdorman::device::Device::Device	(	const __FlashStringHelper *	device_name,
		const __FlashStringHelper *	device_identifier
	)

Construct a new Device object.

Parameters

device_name	Device name.
device_identifier	Device identifier.

Member Function Documentation

◆ as_json()

virtual DynamicJsonDocument grmcdorman::device::Device::as_json ( ) const

inlinevirtual

Get the values, as a JSON document.

The structure is identical to the document created inside publish.

Returns: DynamicJsonDocument

Reimplemented in grmcdorman::device::AbstractAnalog, grmcdorman::device::AbstractTemperaturePressureSensor, grmcdorman::device::InfoDisplay, grmcdorman::device::MqttPublisher, grmcdorman::device::SystemDetailsDisplay, grmcdorman::device::ThermistorSensor, grmcdorman::device::VindriktningAirQuality, grmcdorman::device::WifiDisplay, and grmcdorman::device::WifiSetup.

◆ dataline_to_index()

int grmcdorman::device::Device::dataline_to_index ( int dataLine )

staticprotected

Convert a data line to an index.

This will convert a data line, such as D1, into an index into the settings map.

Parameters

dataLine The data line.

Returns: int An index into the settings map. An unknown data line will return an index of 0, corresponding to D1.

◆ get()

String grmcdorman::device::Device::get ( const String & setting ) const

Get a setting value, as a string.

The setting is located by name, and its value is converted to a string if necessary.

Internally, this search the list of settings for the named setting, and then returns the value of Setting::as_string.

If the setting is not found, an empty string is returned.

Parameters

setting Name of setting.

Returns: Setting's value, as a string; empty string if not found.

◆ get_definitions()

const definition_list_t & grmcdorman::device::Device::get_definitions ( ) const

inline

Get the definitions list.

This returns a static definition list of zero or more sensor definitions.

Returns: A reference to the definition list.

◆ get_firmware_name()

static const __FlashStringHelper * grmcdorman::device::Device::get_firmware_name ( )

inlinestatic

Get the firmware prefix.

Returns: Firmware prefix.

◆ get_is_published()

virtual bool grmcdorman::device::Device::get_is_published ( ) const

inlinevirtual

Get whether the device readings have been published.

The device is considered to be published if there are no readings since the last publish, or since system start.

Returns: true The device readings have been published.; false The device readings have not been published.

Reimplemented in grmcdorman::device::WifiSetup.

◆ get_settings()

const ::grmcdorman::SettingInterface::settings_list_t & grmcdorman::device::Device::get_settings ( ) const

inline

Get the settings list.

This returns a list of zero or more individual settings for this device.

Returns: A reference to the settings list.

◆ get_status()

virtual String grmcdorman::device::Device::get_status ( ) const

inlinevirtual

Get a status report.

This is typically also reported in an info setting. By default this returns an empty string, i.e. no report.

Returns: String containing status report.

Reimplemented in grmcdorman::device::BasicAnalog, grmcdorman::device::DhtSensor, grmcdorman::device::InfoDisplay, grmcdorman::device::MqttPublisher, grmcdorman::device::Sht31Sensor, grmcdorman::device::ThermistorSensor, and grmcdorman::device::VindriktningAirQuality.

◆ get_system_identifier()

static const String & grmcdorman::device::Device::get_system_identifier ( )

inlinestatic

Get the system identifier.

Returns: This is the value set, or generated, when set_system_identifiers is called.

◆ identifier()

virtual const __FlashStringHelper * grmcdorman::device::Device::identifier ( ) const

inlinevirtual

Get the device identifier.

This should be a unique identifier to be used in internal contexts, such as settings files.

Returns: Device identifier.

Reimplemented in grmcdorman::device::SystemDetailsDisplay.

◆ index_to_dataline()

static int grmcdorman::device::Device::index_to_dataline ( int index )

inlinestaticprotected

Convert a data line index to a ESP data line.

The index is simply an offset into the settingsMap array, which contains usable data lines from the D0 ... D8 set defined above.

Parameters

index Index into the settings map.

Returns: int The data line. An out of range index will return D1.

◆ initialize()

void grmcdorman::device::Device::initialize	(	definition_list_t &&	definition_list,
		::grmcdorman::SettingInterface::settings_list_t &&	setting_list
	)

inlineprotected

Initialize the definition and setting lists.

The lists are moved to the private class attributes.

Parameters

definition_list	Device sensor definition list, for MQTT publishing.
setting_list	Device settings, for use by the WebSettings library.

◆ is_enabled()

bool grmcdorman::device::Device::is_enabled ( ) const

inline

Get whether this device is enabled.

Returns: true The device is enabled.; false The device is disabled.

◆ loop()

virtual void grmcdorman::device::Device::loop ( )

pure virtual

Main loop.

This is called in the main application loop. This should avoid blocking as doing so will prevent the other devices from running.

An exception is a "device" which requires user interaction, e.g. WiFi association, before the rest of the system can run.

Implemented in grmcdorman::device::AbstractAnalog, grmcdorman::device::DhtSensor, grmcdorman::device::InfoDisplay, grmcdorman::device::MqttPublisher, grmcdorman::device::Sht31Sensor, grmcdorman::device::SystemDetailsDisplay, grmcdorman::device::VindriktningAirQuality, grmcdorman::device::WifiDisplay, and grmcdorman::device::WifiSetup.

◆ name()

const __FlashStringHelper * grmcdorman::device::Device::name ( ) const

inline

Get the device name; used for UI names and IDs.

Returns: Device name.

◆ publish()

virtual bool grmcdorman::device::Device::publish ( DynamicJsonDocument & json ) const

inlinevirtual

Publish the value and attributes.

The values and attributes for all sensors, i.e. all items listed in the Description instances, should added to the supplied JSON object. If the value is not available, or this device does not publish, return false.

The value, or values, and attributes, if any, are to be added as a single node to the json parameter. This includes the case for multiple sensors.

Parameters

[in,out] json JSON to receive the device values and attributes.

Returns: true if a value to be published was added; false otherwise.

Reimplemented in grmcdorman::device::AbstractTemperaturePressureSensor, grmcdorman::device::AbstractAnalog, grmcdorman::device::VindriktningAirQuality, and grmcdorman::device::WifiSetup.

◆ set()

void grmcdorman::device::Device::set	(	const String &	setting,
		const String &	value
	)

If possible, set a setting's value.

The setting is located by name, and the value is converted from the string if necessary.

If the setting cannot be found, nothing is done.

Internally, this searches the list of settings for the named setting, and then uses Setting::set_from_string.

Parameters

setting	Name of setting.
value	New value for setting.

◆ set_defaults()

virtual void grmcdorman::device::Device::set_defaults ( )

inlinevirtual

Set defaults, if necessary.

This must be called before loading any settings. It will, if necessary, set any defaults that are dynamic; typically these will be values that need the firmware prefix or system identifier.

Reimplemented in grmcdorman::device::MqttPublisher, and grmcdorman::device::WifiSetup.

◆ set_devices()

virtual void grmcdorman::device::Device::set_devices ( const std::vector< Device * > & list )

inlinevirtual

For devices that support it, add devices to manage.

Parameters

list	List of devices to manage.

Reimplemented in grmcdorman::device::InfoDisplay, and grmcdorman::device::MqttPublisher.

◆ set_enabled()

void grmcdorman::device::Device::set_enabled ( bool state )

inline

Set whether this device is enabled.

Parameters

state The new enabled/disabled state.

◆ set_is_published()

void grmcdorman::device::Device::set_is_published ( )

inline

Set the device as having published readings.

This should be called when the device is published.

◆ set_system_identifiers()

void grmcdorman::device::Device::set_system_identifiers	(	const __FlashStringHelper *	firmware_name_value,
		const String &	system_identifier_value = `String()`
	)

static

Set the system identifier values.

This must be called before load; it sets default values. The system identifier is used for default values for things such as host names and SoftAP SSIDs.

The firmware name is a unique identifier for the firmware, or application, using the device.

The system identifier is a unique identifier for the specific board running the application. This is typically constructed at least in part from the hex value of ESP.getChipId() or equivalent. If empty, an identifier is constructed by combining the firmware prefix, a hypen, and the ESP chip ID in hex.

Because these values are system wide, this is a static method.

If this is never called, the firmware prefix is unspecified_firmware and the system identifier is constructed as described above.

Parameters

firmware_name_value	The unique firmware prefix.
system_identifier_value	The system identifier.

◆ setup()

virtual void grmcdorman::device::Device::setup ( )

pure virtual

Setup the device.

Call once when the system boots. This should perform device-specific setup, if the device is enabled, as well as preparing UI settings (notably info settings) for communication.

This must be called after initial values are loaded.

Implemented in grmcdorman::device::AbstractAnalog, grmcdorman::device::DhtSensor, grmcdorman::device::InfoDisplay, grmcdorman::device::MqttPublisher, grmcdorman::device::Sht31Sensor, grmcdorman::device::SystemDetailsDisplay, grmcdorman::device::VindriktningAirQuality, grmcdorman::device::WifiDisplay, and grmcdorman::device::WifiSetup.

Member Data Documentation

◆ settingsMap

const int grmcdorman::device::Device::settingsMap

staticprotected

Initial value:

=
        {
            Device::D1, Device::D2, Device::D3, Device::D5, Device::D6, Device::D7
        }

The set of data lines usable for communication.

This array contains the usable data lines - D1, D2, D3, D5, D6, and D7. It thus is used to translate between indexes in, for example, settings and the internal data line constants.

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

grmcdorman/device/Device.h
Device.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Device()

Member Function Documentation

◆ as_json()

◆ dataline_to_index()

◆ get()

◆ get_definitions()

◆ get_firmware_name()

◆ get_is_published()

◆ get_settings()

◆ get_status()

◆ get_system_identifier()

◆ identifier()

◆ index_to_dataline()

◆ initialize()

◆ is_enabled()

◆ loop()

◆ name()

◆ publish()

◆ set()

◆ set_defaults()

◆ set_devices()

◆ set_enabled()

◆ set_is_published()

◆ set_system_identifiers()

◆ setup()

Member Data Documentation

◆ settingsMap