MQTT: automatically publish NestMTX status

[mrombouts]

Hi Jack,

From the discord discussion: optimize the MQTT implementation with a status topic that gets updated automatically when the status of a camera changes.

Home Automation applications, like MQTT, but also NodeRed and others can then subscribe to this topic and act as needed. Home Assistant can then restart a stream (using MQTT) or even restart the Docker container.

Thanks, Michiel

[jakguru]

Proposal for NestMTX Events

NestMTX Events will be pushed automatically to both the Socket.IO and MQTT APIs.

Topic Format

Due to the difference in the protocols, topics will need to be formatted differently for each protocol.

MQTT Topic Format

MQTT Topics will be constructed as follows:

/<nestmtx base>/events/<domain>/<entity>/<event type>

and

/<nestmtx base>/stream/<domain>/<event type>

The placeholders are defined as follows:

Placeholder	Definition
<nestmtx base>	The base topic as defined by the MQTT_BASE_TOPIC configuration option
<domain>	The type of entity that the event is being reported for. Initial feature release will include camera and credentials
<entity>	An identifier used to identify which entity of the domain the event is being reported for. This will be the id column in the database where possible, or null when not possible
<event type>	The type of event which is being emitted. See the event types below for more information.

Socket.IO Topic Format

Socket.IO Topics (event names) will be constructed as follows:

<domain>:<event type>

The placeholders are defined as follows:

Placeholder	Definition
<domain>	The type of entity that the event is being reported for. Initial feature release will include camera and credentials
<event type>	The type of event which is being emitted. See the event types below for more information.

Additionally, there will be the following wildcard topics:

• <domain:* - Domain specific wildcard topic
• nestmtx:* - Application-wide wildcard topic

Payload Format

Payloads will be JSON objects which can be easily parsed. They will have the following properties:

Payload Property	Description
domain	The type of entity that the event is being reported for. Initial feature release will include camera and credentials
entity	An identifier used to identify which entity of the domain the event is being reported for. This will be the id column in the database where possible, or null when not possible
event	The type of event which is being emitted. See the event types below for more information.
details	Any additional information related to the event that is being triggered to give additional useful context. Will be a JSON object ({}). See event types below for more information

Event Types

The following event types will be reported for the following domains

Event Types for the camera domain

Event	Description
demand	Emitted when a client attempts to read from the camera feed
unDemand	Emitted when no more clients are remaining to read from the camera feed
ready	Emitted when the camera feed is ready to be read from the camera feed
notReady	Emitted when the camera feed is no longer ready to be read from the camera feed
read	Emitted when a client starts consuming the camera feed
unread	Emitted when a client stops consuming the camera feed
extended	Emitted when the source stream authentication has been extended
failed-extension	Emitted when the source stream authentication fails to be extended

Event Types for the credentials domain

Event	Description
authenticated	Emitted when credentials have been authenticated for the first time
reauthenticated	Emitted when credentials have been refreshed using a refresh token
unauthenticated	Emitted when credentials fail to refresh using a refresh token and the credentials need to be reauthenticated

[jakguru]

Note: I've added a second MQTT event structure:

/<nestmtx base>/stream/<domain>/<event type>

This is in order to allow for similar functionality to the "wildcard" topics of the Socket.IO stream where you do not need to subscribe to a specific device's events only - you can subscribe to events for an entire domain.

[jakguru]

Note: Removed some events from the spec since they're duplicates of other events