A component that implements a web-based configuration portal accessible from the local network. More...

#include <ksDevicePortal.h>

Inheritance diagram for ksf::comps::ksDevicePortal:

Public Member Functions
virtual std::size_t	getInstanceType () const
	Retrieves type ID of the object.

virtual bool	isA (const std::size_t id) const
	Checks whether object is of given type.

	ksDevicePortal ()
	Constructs the Device Portal component.

virtual	~ksDevicePortal ()
	Destructs the Device Portal component.

	ksDevicePortal (std::string portalPassword)
	Constructs the Device Portal component with custom password.

bool	init (ksApplication *app) override
	Initializes the device portal component.

bool	postInit (ksApplication *app) override
	Post-initializes the device portal component.

bool	loop (ksApplication *app) override
	Handles core logic of the device portal component.

Public Member Functions inherited from ksf::ksComponent
Public Member Functions inherited from ksf::ksRtti
virtual	~ksRtti ()=default
	Destructor.

template<typename TType >
TType *	as ()
	Tries to cast object to the type provided as a template parameter.

template<typename TType >
const TType *	as () const
	Tries to cast object to the type provided as a template parameter (const version).

Static Public Member Functions
static std::size_t	getClassType ()

Static Public Member Functions inherited from ksf::ksComponent
static std::size_t	getClassType ()

Public Attributes
std::shared_ptr< ksf::evt::ksEvent<> >	onUpdateStart {std::make_shared<ksf::evt::ksEvent<>>()}

std::shared_ptr< ksf::evt::ksEvent<> >	onUpdateEnd {std::make_shared<ksf::evt::ksEvent<>>()}

std::shared_ptr< ksf::evt::ksEvent< const std::string_view &, bool &, std::string & > >	onHandlePortalCommand {std::make_shared<ksf::evt::ksEvent<const std::string_view&, bool&, std::string&>>()}

Protected Member Functions
void	requestAppBreak ()
	Causes the application exit (and ksAppRotator to spawn and process next defined application).

void	triggerFactoryReset ()
	Triggers factory reset (erase config and reboot).

void	setupHttpServer ()
	Starts device portal HTTP server.

void	setupWsServer ()
	Starts device portal WebSocket server.

void	updateFinished (bool fromPortal)
	Implements post-OTA update actions.

void	rebootDevice ()
	Reboots the device.

bool	inRequest_NeedAuthentication ()
	Checks if current HTTP request requires authentication.

void	onRequest_notFound () const
	HTTP handler for 404 "not found" endpoint.

void	onRequest_index ()
	HTTP handler for index endpoint.

void	onRequest_otaChunk ()
	HTTP handler for OTA chunk endpoint.

void	onRequest_otaFinish ()
	HTTP handler for OTA finish endpoint.

void	onWebsocketTextMessage (uint8_t clientNum, const std::string_view &message)
	Handles websocket text message.

void	handle_scanNetworks (std::string &response)
	Websocket handler for network scan endpoint.

void	handle_getIdentity (std::string &response)
	Websocket handler for identity endpoint (device details).

void	handle_getDeviceParams (std::string &response)
	Websocket handler for device parameters endpoint.

std::string	handle_executeCommand (const std::string_view &body)
	Websocket handler for user commands endpoint.

void	onAppLog (std::string &&message)
	Broadcasts application log message to all connected Websocket clients.

Protected Attributes
ksf::ksApplication *	app {nullptr}
	Application pointer.

struct {

bool breakApp: 1
	Flag to break app logic.

bool isSafeToCallEndOta: 1
	Flag indicating that OTA class is initialized.

}	bitflags = {false, false}
	Bit flags for internal use.

uint32_t	logKeepAliveTimestamp {0}
	Flag indicating whether logs are enabled.

uint32_t	lastLoopExecutionTimestamp {0}
	Time of last loop execution (us).

uint32_t	loopExecutionTime {0}
	Diff (loop exec time).

uint32_t	scanNetworkTimestamp {0}
	Timestamp of last scan.

std::string	portalPassword
	Portal password.

std::weak_ptr< ksMqttConnector >	mqttConnectorWp
	MQTT connector.

std::unique_ptr< WebServerClass >	webServer
	HTTP server.

std::unique_ptr< misc::ksWSServer >	webSocket
	Web socket server.

std::unique_ptr< DNSServer >	dnsServer
	DNS server.

std::unique_ptr< ArduinoOTAClass >	arduinoOTA
	Arduino OTA object.

Protected Attributes inherited from ksf::ksComponent
ksComponentState::TYPE	componentState { ksComponentState::NotInitialized }
	Holds current state of the component.

Detailed Description

A component that implements a web-based configuration portal accessible from the local network.

The portal allows OTA updates in both access point and station modes. It also includes a web-based terminal for debugging the device and viewing real-time application logs.

In a configurator application, do not add this component directly; use ksWifiConfigurator instead. In a "normal application," you must manually add the component if you wish to use it.

Constructor & Destructor Documentation

◆ ksDevicePortal() [1/2]

ksf::comps::ksDevicePortal::ksDevicePortal ( )

Constructs the Device Portal component.

Uses the default password "ota_ksiotframework"

◆ ksDevicePortal() [2/2]

ksf::comps::ksDevicePortal::ksDevicePortal ( std::string portalPassword )

Constructs the Device Portal component with custom password.

Parameters

password Password used to authenticate the user.

References arduinoOTA.

Member Function Documentation

◆ getInstanceType()

virtual std::size_t ksf::comps::ksDevicePortal::getInstanceType ( ) const

inlinevirtual

Retrieves type ID of the object.

Returns: Object type ID.

Reimplemented from ksf::ksComponent.

◆ handle_executeCommand()

std::string ksf::comps::ksDevicePortal::handle_executeCommand ( const std::string_view & body )

protected

Websocket handler for user commands endpoint.

Parameters

body	Command string from the browser.

Returns: String with command execution result.

References ksf::evt::ksEvent< Params >::broadcast(), onHandlePortalCommand, rebootDevice(), and triggerFactoryReset().

Referenced by onWebsocketTextMessage().

◆ handle_getDeviceParams()

void ksf::comps::ksDevicePortal::handle_getDeviceParams ( std::string & response )

protected

Websocket handler for device parameters endpoint.

Parameters

response Response reference . This method will output device configuration parameters into this string.

References app, and ksf::ksApplication::findComponents().

Referenced by onWebsocketTextMessage().

◆ handle_getIdentity()

void ksf::comps::ksDevicePortal::handle_getIdentity ( std::string & response )

protected

Websocket handler for identity endpoint (device details).

Parameters

response Response reference. This method will output device details in JSON format into this string.

References loopExecutionTime, and mqttConnectorWp.

Referenced by onWebsocketTextMessage().

◆ handle_scanNetworks()

void ksf::comps::ksDevicePortal::handle_scanNetworks ( std::string & response )

protected

Websocket handler for network scan endpoint.

Parameters

response Response reference. This method will output network scan results in JSON format into this string.

References scanNetworkTimestamp.

Referenced by onWebsocketTextMessage().

◆ init()

bool ksf::comps::ksDevicePortal::init ( ksApplication * app )

overridevirtual

Initializes the device portal component.

Parameters

app	Pointer to the parent ksApplication.

Returns: True on success, false otherwise.

Reimplemented from ksf::ksComponent.

References app.

◆ isA()

virtual bool ksf::comps::ksDevicePortal::isA ( const std::size_t id ) const

inlinevirtual

Checks whether object is of given type.

Parameters

id	Type ID to check against.

Returns: True if object is of given type, otherwise false.

Reimplemented from ksf::ksComponent.

◆ loop()

bool ksf::comps::ksDevicePortal::loop ( ksApplication * app )

overridevirtual

Handles core logic of the device portal component.

Parameters

app	Pointer to the parent ksApplication.

Returns: True on success, false otherwise.

Reimplemented from ksf::ksComponent.

References app, arduinoOTA, bitflags, dnsServer, lastLoopExecutionTimestamp, logKeepAliveTimestamp, loopExecutionTime, scanNetworkTimestamp, webServer, and webSocket.

◆ onAppLog()

void ksf::comps::ksDevicePortal::onAppLog ( std::string && message )

protected

Broadcasts application log message to all connected Websocket clients.

Parameters

message R-value reference of the message to broadcast.

References webSocket.

Referenced by onWebsocketTextMessage().

◆ onRequest_index()

void ksf::comps::ksDevicePortal::onRequest_index ( )

protected

HTTP handler for index endpoint.

Called when the browser requests "/" endpoint. This is the default endpoint.

References inRequest_NeedAuthentication(), webServer, and webSocket.

Referenced by setupHttpServer().

◆ onRequest_notFound()

void ksf::comps::ksDevicePortal::onRequest_notFound ( ) const

protected

HTTP handler for 404 "not found" endpoint.

Called when the browser requests an endpoint that doesn't exist.

References webServer.

Referenced by setupHttpServer().

◆ onRequest_otaChunk()

void ksf::comps::ksDevicePortal::onRequest_otaChunk ( )

protected

HTTP handler for OTA chunk endpoint.

Called when the browser requests "/api/flash" endpoint with next firmware upload part. Used also to notify the browser about firmware uplaod progress.

References ksf::evt::ksEvent< Params >::broadcast(), inRequest_NeedAuthentication(), onUpdateStart, and webServer.

Referenced by setupHttpServer().

◆ onRequest_otaFinish()

void ksf::comps::ksDevicePortal::onRequest_otaFinish ( )

protected

HTTP handler for OTA finish endpoint.

Called when the browser requests "/api/flash" endpoint and the upload is complete. Used also to tell the browser that the upload is complete (or failed).

References inRequest_NeedAuthentication(), rebootDevice(), updateFinished(), and webServer.

Referenced by setupHttpServer().

◆ onWebsocketTextMessage()

void ksf::comps::ksDevicePortal::onWebsocketTextMessage	(	uint8_t	clientNum,
		const std::string_view &	message )

protected

Handles websocket text message.

Parameters

clientNum	Number of Websocket client (used as ID to know who's the sender).
message	String view of the message content.

References app, ksf::ksApplication::findComponents(), handle_executeCommand(), handle_getDeviceParams(), handle_getIdentity(), handle_scanNetworks(), logKeepAliveTimestamp, onAppLog(), requestAppBreak(), triggerFactoryReset(), and webSocket.

Referenced by setupWsServer().

◆ postInit()

bool ksf::comps::ksDevicePortal::postInit ( ksApplication * app )

overridevirtual

Post-initializes the device portal component.

Parameters

app	Pointer to the parent ksApplication.

Returns: True on success, false otherwise.

Reimplemented from ksf::ksComponent.

References app, arduinoOTA, bitflags, dnsServer, ksf::ksApplication::findComponent(), mqttConnectorWp, setupHttpServer(), and setupWsServer().

Member Data Documentation

◆ onHandlePortalCommand

std::shared_ptr<ksf::evt::ksEvent<const std::string_view&, bool&, std::string&> > ksf::comps::ksDevicePortal::onHandlePortalCommand {std::make_shared<ksf::evt::ksEvent<const std::string_view&, bool&, std::string&>>()}

Custom command handler event.

Parameters

param_1	String view of the command coming from the browser.
param_2	Reference of boolean value indicating if the command was handled. Set to true to stop further processing and return response.
param_3	Reference of the string containing the command response. Append results here.

Referenced by handle_executeCommand().

◆ onUpdateEnd

std::shared_ptr<ksf::evt::ksEvent<> > ksf::comps::ksDevicePortal::onUpdateEnd {std::make_shared<ksf::evt::ksEvent<>>()}

Update end (OTA) event. No parameters.

Referenced by updateFinished().

◆ onUpdateStart

std::shared_ptr<ksf::evt::ksEvent<> > ksf::comps::ksDevicePortal::onUpdateStart {std::make_shared<ksf::evt::ksEvent<>>()}

Update start (OTA) event. No parameters.

Referenced by onRequest_otaChunk().

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

src/ksf/comp/ksDevicePortal.h
src/ksf/comp/ksDevicePortal.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ksDevicePortal() [1/2]

◆ ksDevicePortal() [2/2]

Member Function Documentation

◆ getInstanceType()

◆ handle_executeCommand()

◆ handle_getDeviceParams()

◆ handle_getIdentity()

◆ handle_scanNetworks()

◆ init()

◆ isA()

◆ loop()

◆ onAppLog()

◆ onRequest_index()

◆ onRequest_notFound()

◆ onRequest_otaChunk()

◆ onRequest_otaFinish()

◆ onWebsocketTextMessage()

◆ postInit()

Member Data Documentation

◆ onHandlePortalCommand

◆ onUpdateEnd

◆ onUpdateStart