Wi-Fi access: when the panel's radio runs, under which name, and who the page answers. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Data Structures
struct	wa_conf_t
	What is kept: the home network and the code switch. More...
struct	wa_store_t
	The store a wa_conf_t is kept in. More...
struct	wa_pending_t
	The writes owed to the store. More...
struct	wa_net_t
	One network of the scan list. More...
struct	wa_scan_t
	The scan list, strongest first. More...
struct	wa_t
	A session: what the radio should do, and where it is. More...

Macros
#define	WA_SCAN_MAX 16u
	Networks the scan list holds.
Limits and times
#define	WA_SECRET_LEN 8u
#define	WA_SECRET_CHARS "abcdefghjkmnpqrstuvwxyz23456789"
#define	WA_NAME_MAX 13u
#define	WA_SSID_MAX 32u
	A home network's name, in bytes.
#define	WA_PASS_MIN 8u
	A WPA2/WPA3 passphrase's fewest characters.
#define	WA_PASS_MAX 63u
	A WPA2/WPA3 passphrase's most characters.
#define	WA_IDLE_MS (10u * 60u * 1000u)
#define	WA_JOIN_MS 20000u
#define	WA_AUTH_TRIES 3u
	Auth-class drops in a row that end a join as WA_JOIN_PASSWORD.
#define	WA_ADDRESS_MS 15000u
#define	WA_START_MS 10000u
#define	WA_SCAN_TRIES 3u
	Scans a scan session starts at most: the first, and one more after each scan the radio reports failed, all within WA_START_MS.
#define	WA_GUESS_MAX 16u
The writes owed to the store
A change lands in memory at once and in the store on a frame that may write flash (wa_pending_due()). A flag is cleared only by a write that succeeded and that no later change overtook. A failed write is shown (failed) and tried again WA_PENDING_RETRIES times, WA_PENDING_RETRY_MS apart; after that it waits for the next change, which tries at once and starts the count again.
#define	WA_PENDING_RETRIES 3u
	Automatic tries after a failed write.
#define	WA_PENDING_RETRY_MS 10000u
	The time between them, ms.
The ways the screen offers
#define	WA_CAN_AP 0x1u
	The access point, always.
#define	WA_CAN_JOIN 0x2u
	The home network, when one is kept.

Typedefs
typedef uint32_t(*)	wa_rand_fn(void *ctx)
	A source of random 32-bit words.

Enumerations
enum	wa_conf_err_t { WA_CONF_OK = 0 , WA_CONF_SSID_EMPTY , WA_CONF_SSID_LONG , WA_CONF_SSID_CHAR , WA_CONF_PASS_SHORT , WA_CONF_PASS_LONG , WA_CONF_PASS_CHAR }
	Why wa_conf_set_net() refused a home network. More...
enum	wa_mode_t { WA_MODE_AP = 0 , WA_MODE_JOIN , WA_MODE_SCAN , WA_MODE_FETCH }
	What a session is for. More...
enum	wa_state_t { WA_ST_OFF = 0 , WA_ST_STARTING , WA_ST_AP , WA_ST_SCANNING , WA_ST_JOINING , WA_ST_ADDRESS , WA_ST_JOINED }
	Where a session is. More...
enum	wa_off_t { WA_OFF_NONE = 0 , WA_OFF_ARMED , WA_OFF_SUPPLY , WA_OFF_RUN , WA_OFF_STOP , WA_OFF_IDLE , WA_OFF_GUESSES , WA_OFF_ASKED , WA_OFF_INSTALL , WA_OFF_FAILED , WA_OFF_JOIN }
	Why the radio is off. More...
enum	wa_join_err_t { WA_JOIN_OK = 0 , WA_JOIN_PASSWORD , WA_JOIN_NOT_FOUND , WA_JOIN_NO_ADDRESS , WA_JOIN_LOST }
	Why a join failed. More...
enum	wa_scan_step_t { WA_SCAN_IGNORE = 0 , WA_SCAN_TAKE , WA_SCAN_AGAIN , WA_SCAN_FAILED }
	What the platform does with a scan the radio reports done (wa_on_scan_end()). More...
enum	wa_code_t { WA_CODE_OK = 0 , WA_CODE_MISSING , WA_CODE_WRONG , WA_CODE_CLOSED }
	What the access code check says of a request. More...

Functions
void	wa_secret_make (char out[WA_SECRET_LEN+1u], wa_rand_fn rand, void *ctx)
	WA_SECRET_LEN characters of WA_SECRET_CHARS and a terminator, each drawn evenly from the alphabet (words that would favour some characters are drawn again).
void	wa_name (const uint8_t mac[6], char out[WA_NAME_MAX])
	"rcbench-" and the last two bytes of `mac` in capital hex.
void	wa_conf_defaults (wa_conf_t *c)
	No home network, the code on: a fresh store, and what FORGET leaves.
wa_conf_err_t	wa_conf_set_net (wa_conf_t c, const char ssid, size_t ssid_len, const char *pass, size_t pass_len)
	Take a home network.
void	wa_conf_load (const wa_store_t s, wa_conf_t out)
	What the store holds, or the defaults when it holds nothing.
bool	wa_conf_save (const wa_store_t s, const wa_conf_t c)
	Write `c` into the store.
bool	wa_conf_forget (const wa_store_t s, wa_conf_t c)
	FORGET: erase the store and leave `c` at the defaults.
void	wa_pending_init (wa_pending_t *p)
	Nothing owed.
void	wa_pending_change (wa_pending_t *p)
	A change of the settings in memory: owe a save.
void	wa_pending_forget (wa_pending_t *p)
	FORGET: owe an erase; a save owed before it is void.
bool	wa_pending_due (const wa_pending_t *p, bool may_write, uint32_t now_ms)
	Whether a write is owed and due now.
void	wa_pending_write (const wa_store_t st, const wa_pending_t snap, const wa_conf_t c, bool erase_ok, bool *save_ok)
	Write what `snap` owes – the erase, then `c` – into `st`.
void	wa_pending_done (wa_pending_t p, const wa_pending_t snap, bool erase_ok, bool save_ok, uint32_t now_ms)
	Record the results of a write that started from `snap`.
unsigned	wa_modes (const wa_conf_t *c)
	Which ways the screen offers.
void	wa_scan_clear (wa_scan_t *s)
	Empty the scan list.
void	wa_scan_add (wa_scan_t s, const uint8_t ssid, size_t len, int8_t rssi, bool usable)
	One network a scan saw.
const char *	wa_scan_pick (const wa_scan_t *s, unsigned i)
	The name at row `i`.
void	wa_init (wa_t *w)
	Off, nothing kept of any session.
wa_off_t	wa_gate (bool armed, bool supply, bool run)
	Why the radio may not run now.
wa_off_t	wa_start (wa_t w, wa_mode_t mode, wa_off_t gate, uint32_t now_ms, wa_rand_fn rand, void ctx)
	Start in `mode` when `gate` is WA_OFF_NONE, with a fresh password and code.
void	wa_close (wa_t *w, wa_off_t why)
	Switch off for `why`.
bool	wa_radio (const wa_t *w)
	Whether the platform's radio should be running.
bool	wa_lingers (const wa_t *w)
	Whether the radio may stay up past the session's end, for a request of the platform's own that is under way (the clock's NTP request, wall_ntp_holds()).
void	wa_unlinger (wa_t *w)
	The platform needs the radio off now: a linger ends; a session that runs goes on.
bool	wa_serving (const wa_t *w)
	Whether the page is being served.
void	wa_on_ap_up (wa_t *w, uint32_t now_ms)
	The access point came up.
void	wa_on_scan_done (wa_t *w)
	A scan session's list was read: the session ends, off WA_OFF_NONE. wa_on_scan_end() does it with the scan's result.
void	wa_on_associated (wa_t *w, uint32_t now_ms)
	The station reached the home network.
void	wa_on_address (wa_t *w, uint32_t ip, uint32_t now_ms)
	The station has an address.
void	wa_on_join_failed (wa_t *w, wa_join_err_t why)
	A join failed or a joined network went away.
bool	wa_on_drop (wa_t *w, bool auth)
	The radio dropped the station.
void	wa_on_failed (wa_t *w)
	The radio could not be started: off WA_OFF_FAILED. A refused scan is wa_scan_refused().
uint32_t	wa_scan_begin (wa_t *w)
	The radio's station started in a scan session: the token of the scan the platform starts now, or 0 for none.
uint32_t	wa_scan_pending (const wa_t *w)
	The scan of this session under way, its done report still owed.
bool	wa_scan_is (const wa_t *w, uint32_t tok)
	Whether the scan of `tok` is the one under way.
bool	wa_scan_refused (wa_t *w, uint32_t tok)
	The radio refused to start the scan of `tok:` off WA_OFF_FAILED when it is the scan under way.
bool	wa_scan_read_ok (uint32_t status, unsigned reported, bool read_ok, unsigned read, unsigned room)
	Whether a scan reported done counts as done.
wa_scan_step_t	wa_on_scan_end (wa_t w, uint32_t tok, bool ok, uint32_t next)
	The scan of `tok` reported done; `ok` as wa_scan_read_ok() says.
bool	wa_tick (wa_t *w, uint32_t now_ms, wa_off_t gate, bool stop)
	Once a frame: the gate, STOP and the time-outs. Off, a gate or STOP ends a linger (wa_lingers()).
void	wa_request_begin (wa_t *w, uint32_t now_ms)
	A request begins; one under way holds the idle time-out off.
void	wa_request_end (wa_t *w, uint32_t now_ms)
	A request ends; the idle time counts from now.
uint32_t	wa_idle_left (const wa_t *w, uint32_t now_ms)
	The time left before the idle time-out.
wa_code_t	wa_code_check (wa_t w, const char given, bool code_on)
	Check `given` against this session's code.

Detailed Description

Wi-Fi access: when the panel's radio runs, under which name, and who the page answers.

The panel offers a browser page for two jobs: a panel firmware upload and the card's files for download. It reaches the browser one of two ways:

ACCESS POINT its own network, 2.4GHz, WPA2 (Wi-Fi Protected Access 2), named "rcbench-" and 4 hex digits of the MAC (media access control) address, with a password of WA_SECRET_LEN characters made fresh at every start; one client at a time HOME NETWORK the network whose name and password the operator typed on the panel and the panel keeps

The radio runs only while the Wi-Fi screen asks for it, or while the panel asks GitHub for a release (WA_MODE_FETCH, wa_fetch.h). It is off at every start of the panel, and it goes off on its own: on ARM, on STOP, on the supply coming on, on a log run opening, after WA_IDLE_MS without a request, and after WA_GUESS_MAX wrong access codes. A joined session switched off by the operator or by WA_IDLE_MS may leave the radio up for the platform's last request on the network (wa_lingers()).

The access code: WA_SECRET_LEN characters shown on the panel, made fresh at every start, which the page asks for before it lists a file or takes an upload. A switch on the screen turns it off; it is on by default.

What is kept: the home network's name and password and the code switch (wa_conf_t), in a store the caller passes (NVS, non-volatile storage, on the panel). Nothing else about Wi-Fi is kept.

Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework): the platform reports what its radio did and asks what it should do.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ WA_ADDRESS_MS

#define WA_ADDRESS_MS 15000u

A join that reached the network and has no address after this long.

◆ WA_AUTH_TRIES

#define WA_AUTH_TRIES 3u

Auth-class drops in a row that end a join as WA_JOIN_PASSWORD.

The radio reports a refused key and a key handshake that ran out of time with the same reasons, and a correct key times out when the panel or the router answers late; one drop says nothing about the password.

◆ WA_GUESS_MAX

#define WA_GUESS_MAX 16u

Wrong access codes before the radio goes off.

◆ WA_IDLE_MS

#define WA_IDLE_MS (10u * 60u * 1000u)

The radio goes off after this long without a request.

◆ WA_JOIN_MS

#define WA_JOIN_MS 20000u

A join that has not reached the network after this long failed.

◆ WA_NAME_MAX

#define WA_NAME_MAX 13u

"rcbench-1A2B" and its terminator.

◆ WA_SECRET_CHARS

#define WA_SECRET_CHARS "abcdefghjkmnpqrstuvwxyz23456789"

What a secret is made of: no 0, 1, i, l or o, which read alike.

◆ WA_SECRET_LEN

#define WA_SECRET_LEN 8u

Characters of the access point's password and of the access code.

◆ WA_START_MS

#define WA_START_MS 10000u

A start of the access point, or a scan, that has not come up.

Typedef Documentation

◆ wa_rand_fn

typedef uint32_t(*) wa_rand_fn(void *ctx)

A source of random 32-bit words.

Parameters

ctx	The caller's context.

Returns: The next word.

Enumeration Type Documentation

◆ wa_code_t

enum wa_code_t

What the access code check says of a request.

Enumerator
WA_CODE_OK	the right code, or the code off
WA_CODE_MISSING	none sent: the page asks for it
WA_CODE_WRONG	counted toward WA_GUESS_MAX
WA_CODE_CLOSED	no session

◆ wa_conf_err_t

enum wa_conf_err_t

Why wa_conf_set_net() refused a home network.

Enumerator
WA_CONF_OK	taken
WA_CONF_SSID_EMPTY	no name
WA_CONF_SSID_LONG	over WA_SSID_MAX bytes
WA_CONF_SSID_CHAR	a NUL byte in it
WA_CONF_PASS_SHORT	under WA_PASS_MIN characters
WA_CONF_PASS_LONG	over WA_PASS_MAX characters
WA_CONF_PASS_CHAR	a character outside printable ASCII

◆ wa_join_err_t

enum wa_join_err_t

Why a join failed.

Enumerator
WA_JOIN_OK	no join failed
WA_JOIN_PASSWORD	the network refused the password
WA_JOIN_NOT_FOUND	no such network in reach
WA_JOIN_NO_ADDRESS	no address within WA_ADDRESS_MS
WA_JOIN_LOST	joined, then the network went away

◆ wa_mode_t

enum wa_mode_t

What a session is for.

Enumerator
WA_MODE_AP	the access point and the page
WA_MODE_JOIN	the home network and the page
WA_MODE_SCAN	a scan for the home network list, no page
WA_MODE_FETCH	The home network for the panel's own requests to GitHub (wa_fetch.h): no page, no name, no access code asked.

◆ wa_off_t

enum wa_off_t

Why the radio is off.

Enumerator
WA_OFF_NONE	never started, or a scan finished
WA_OFF_ARMED	ARM, or an arm waiting
WA_OFF_SUPPLY	the supply's output on or queued on
WA_OFF_RUN	a log run is open
WA_OFF_STOP	STOP
WA_OFF_IDLE	WA_IDLE_MS without a request
WA_OFF_GUESSES	WA_GUESS_MAX wrong access codes
WA_OFF_ASKED	the operator switched it off
WA_OFF_INSTALL	an install is about to write the flash
WA_OFF_FAILED	the radio did not come up
WA_OFF_JOIN	a join failed: see wa_t.join_err

◆ wa_scan_step_t

enum wa_scan_step_t

What the platform does with a scan the radio reports done (wa_on_scan_end()).

Enumerator
WA_SCAN_IGNORE	not the scan under way: nothing changed
WA_SCAN_TAKE	keep the list read; the session ended, off WA_OFF_NONE
WA_SCAN_AGAIN	start the next scan of the session now
WA_SCAN_FAILED	the session ended, off WA_OFF_FAILED

◆ wa_state_t

enum wa_state_t

Where a session is.

Enumerator
WA_ST_OFF	the radio is off
WA_ST_STARTING	the access point or the scan is coming up
WA_ST_AP	the access point is up
WA_ST_SCANNING	a scan session, its list not read yet
WA_ST_JOINING	looking for the home network
WA_ST_ADDRESS	on the home network, waiting for an address
WA_ST_JOINED	on the home network with an address

Function Documentation

◆ wa_close()

void wa_close	(	wa_t *	w,
		wa_off_t	why )

Switch off for why.

A joined session switched off by the operator (WA_OFF_ASKED, which is also a release check's own end) or by WA_IDLE_MS lingers (wa_lingers()). Already off: only a reason that does not linger acts, and it ends the linger.

Parameters

w	The session.
why	The reason.

◆ wa_code_check()

wa_code_t wa_code_check	(	wa_t *	w,
		const char *	given,
		bool	code_on )

Check given against this session's code.

A code from an earlier session is wrong. The WA_GUESS_MAX-th wrong one switches the session off.

Parameters

w	The session.
given	The code sent, NULL or terminated.
code_on	The code switch; false passes every request while the page is served.

Returns: The check's answer; WA_CODE_CLOSED when no page is served.

◆ wa_conf_defaults()

void wa_conf_defaults ( wa_conf_t * c )

No home network, the code on: a fresh store, and what FORGET leaves.

Parameters

c	Receives the defaults.

◆ wa_conf_forget()

bool wa_conf_forget	(	const wa_store_t *	s,
		wa_conf_t *	c )

FORGET: erase the store and leave c at the defaults.

Parameters

s	The store.
c	The settings.

Returns: Whether the erase worked.

◆ wa_conf_load()

void wa_conf_load	(	const wa_store_t *	s,
		wa_conf_t *	out )

What the store holds, or the defaults when it holds nothing.

A kept network that wa_conf_set_net() would refuse is dropped; the switch stays.

Parameters

s	The store.
out	Receives the settings.

◆ wa_conf_save()

bool wa_conf_save	(	const wa_store_t *	s,
		const wa_conf_t *	c )

Write c into the store.

Parameters

s	The store.
c	The settings.

Returns: Whether the write worked.

◆ wa_conf_set_net()

wa_conf_err_t wa_conf_set_net	(	wa_conf_t *	c,
		const char *	ssid,
		size_t	ssid_len,
		const char *	pass,
		size_t	pass_len )

Take a home network.

ssid of ssid_len bytes, 1 to WA_SSID_MAX, no NUL; pass of pass_len characters, WA_PASS_MIN to WA_PASS_MAX, each printable ASCII (American Standard Code for Information Interchange, 0x20 to 0x7E).

Parameters

c	The settings; unchanged unless WA_CONF_OK.
ssid	The network's name, not terminated.
ssid_len	Its bytes.
pass	The passphrase, not terminated.
pass_len	Its characters.

Returns: WA_CONF_OK, or what is wrong with the pair.

◆ wa_gate()

wa_off_t wa_gate	(	bool	armed,
		bool	supply,
		bool	run )

Why the radio may not run now.

Parameters

armed	As flash_gate_open() takes it.
supply	Likewise.
run	A log run is open.

Returns: The reason, or WA_OFF_NONE.

◆ wa_idle_left()

uint32_t wa_idle_left	(	const wa_t *	w,
		uint32_t	now_ms )

The time left before the idle time-out.

Parameters

w	The session.
now_ms	Now.

Returns: ms; 0 while a request is under way or no page is served.

◆ wa_init()

void wa_init ( wa_t * w )

Off, nothing kept of any session.

Parameters

w	The session.

◆ wa_lingers()

bool wa_lingers ( const wa_t * w )

Whether the radio may stay up past the session's end, for a request of the platform's own that is under way (the clock's NTP request, wall_ntp_holds()).

Only a joined session switched off for WA_OFF_ASKED or WA_OFF_IDLE lingers. The linger ends at once with a gate (ARM, the supply, a log run), STOP, any other wa_close() reason (an install, a failed radio), a drop of the station and any wa_start(); a new session's start takes the radio down first.

Parameters

w	The session.

Returns: true while the session is off and lingers.

◆ wa_modes()

unsigned wa_modes ( const wa_conf_t * c )

Which ways the screen offers.

Parameters

c	The settings; NULL offers the access point only.

Returns: WA_CAN_AP, with WA_CAN_JOIN when a home network is kept.

◆ wa_name()

void wa_name	(	const uint8_t	mac[6],
		char	out[WA_NAME_MAX] )

"rcbench-" and the last two bytes of mac in capital hex.

Parameters

mac	The radio's MAC address.
out	Receives the name, terminated.

◆ wa_on_address()

void wa_on_address	(	wa_t *	w,
		uint32_t	ip,
		uint32_t	now_ms )

The station has an address.

Parameters

w	The session.
ip	The address, network byte order.
now_ms	Now.

◆ wa_on_ap_up()

void wa_on_ap_up	(	wa_t *	w,
		uint32_t	now_ms )

The access point came up.

Parameters

w	The session.
now_ms	Now.

◆ wa_on_associated()

void wa_on_associated	(	wa_t *	w,
		uint32_t	now_ms )

The station reached the home network.

Parameters

w	The session.
now_ms	Now.

◆ wa_on_drop()

bool wa_on_drop	(	wa_t *	w,
		bool	auth )

The radio dropped the station.

Joining: an auth-class drop counts, any other drop clears the count, and the WA_AUTH_TRIES-th auth-class drop in a row ends the join as WA_JOIN_PASSWORD. On the network, with or without an address: WA_JOIN_LOST. A join that reaches WA_JOIN_MS ends as WA_JOIN_PASSWORD when its last drop was auth-class, and as WA_JOIN_NOT_FOUND after any other drop or none (wa_tick()).

Parameters

w	The session.
auth	The platform reads the reason as auth-class (the key refused, a MIC (message integrity code) failure, the key handshake out of time).

Returns: Whether the platform asks the radio to connect again: true while the join goes on.

◆ wa_on_failed()

void wa_on_failed ( wa_t * w )

The radio could not be started: off WA_OFF_FAILED. A refused scan is wa_scan_refused().

Parameters

w	The session.

◆ wa_on_join_failed()

void wa_on_join_failed	(	wa_t *	w,
		wa_join_err_t	why )

A join failed or a joined network went away.

Parameters

w	The session.
why	As the platform reads its reason code.

◆ wa_on_scan_done()

void wa_on_scan_done ( wa_t * w )

A scan session's list was read: the session ends, off WA_OFF_NONE. wa_on_scan_end() does it with the scan's result.

Parameters

w	The session.

◆ wa_on_scan_end()

wa_scan_step_t wa_on_scan_end	(	wa_t *	w,
		uint32_t	tok,
		bool	ok,
		uint32_t *	next )

The scan of tok reported done; ok as wa_scan_read_ok() says.

A report for a scan that is not the one under way changes nothing. A failed scan is started again while WA_SCAN_TRIES allows; the last one failed ends the session WA_OFF_FAILED, never as an empty list.

Parameters

w	The session.
tok	The token of the scan the report was read for.
ok	The scan worked and its list was read.
next	Receives the token of the scan to start with WA_SCAN_AGAIN, 0 otherwise.

Returns: What the platform does next.

◆ wa_pending_change()

void wa_pending_change ( wa_pending_t * p )

A change of the settings in memory: owe a save.

Parameters

p	The writes owed.

◆ wa_pending_done()

void wa_pending_done	(	wa_pending_t *	p,
		const wa_pending_t *	snap,
		bool	erase_ok,
		bool	save_ok,
		uint32_t	now_ms )

Record the results of a write that started from snap.

Parameters

p	The writes owed.
snap	The copy the write started from.
erase_ok	The erase's result.
save_ok	The save's result.
now_ms	Now.

◆ wa_pending_due()

bool wa_pending_due	(	const wa_pending_t *	p,
		bool	may_write,
		uint32_t	now_ms )

Whether a write is owed and due now.

Parameters

p	The writes owed.
may_write	This frame may write flash.
now_ms	Now.

Returns: true when the caller writes now.

◆ wa_pending_forget()

void wa_pending_forget ( wa_pending_t * p )

FORGET: owe an erase; a save owed before it is void.

Parameters

p	The writes owed.

◆ wa_pending_init()

void wa_pending_init ( wa_pending_t * p )

Nothing owed.

Parameters

p	The writes owed.

◆ wa_pending_write()

void wa_pending_write	(	const wa_store_t *	st,
		const wa_pending_t *	snap,
		const wa_conf_t *	c,
		bool *	erase_ok,
		bool *	save_ok )

Write what snap owes – the erase, then c – into st.

Runs without the caller's lock; snap and c are copies taken with wa_pending_due() under it.

Parameters

st	The store.
snap	The writes owed, a copy.
c	The settings, a copy.
erase_ok	Receives the erase's result; true for one not owed.
save_ok	Receives the save's result; true for one not owed.

◆ wa_radio()

bool wa_radio ( const wa_t * w )

Whether the platform's radio should be running.

Parameters

w	The session.

Returns: true for any state but WA_ST_OFF.

◆ wa_request_begin()

void wa_request_begin	(	wa_t *	w,
		uint32_t	now_ms )

A request begins; one under way holds the idle time-out off.

Parameters

w	The session.
now_ms	Now.

◆ wa_request_end()

void wa_request_end	(	wa_t *	w,
		uint32_t	now_ms )

A request ends; the idle time counts from now.

Parameters

w	The session.
now_ms	Now.

◆ wa_scan_add()

void wa_scan_add	(	wa_scan_t *	s,
		const uint8_t *	ssid,
		size_t	len,
		int8_t	rssi,
		bool	usable )

One network a scan saw.

Kept when usable (WPA2 or WPA3 personal) and named; a name already listed keeps the stronger signal. The list is held strongest first, and a full list keeps the WA_SCAN_MAX strongest.

Parameters

s	The list.
ssid	The name, `len` bytes, not terminated.
len	Its bytes.
rssi	Its signal, dBm.
usable	WPA2 or WPA3 personal.

◆ wa_scan_begin()

uint32_t wa_scan_begin ( wa_t * w )

The radio's station started in a scan session: the token of the scan the platform starts now, or 0 for none.

One scan at a time: a second report of the station's start while a scan runs starts none, as a second esp_wifi_scan_start() would replace the first and report it done with nothing found. Each scan has its own token, never 0, which the platform carries through the calls that run outside its lock: a refusal (wa_scan_refused()), a done report (wa_on_scan_end()) and a retry (wa_scan_is()) act only on the scan under way, never on a session started after it.

Parameters

w	The session.

Returns: The scan's token, once per scan session, with the session scanning and no scan under way; 0 otherwise.

◆ wa_scan_clear()

void wa_scan_clear ( wa_scan_t * s )

Empty the scan list.

Parameters

s The list.

◆ wa_scan_is()

bool wa_scan_is	(	const wa_t *	w,
		uint32_t	tok )

Whether the scan of tok is the one under way.

Parameters

w	The session.
tok	A token wa_scan_begin() or wa_on_scan_end() gave.

Returns: true for the scan under way; false for 0, for a scan that ended and for one of an earlier session.

◆ wa_scan_pending()

uint32_t wa_scan_pending ( const wa_t * w )

The scan of this session under way, its done report still owed.

Parameters

w	The session.

Returns: Its token, or 0 for none.

◆ wa_scan_pick()

const char * wa_scan_pick	(	const wa_scan_t *	s,
		unsigned	i )

The name at row i.

Parameters

s	The list; NULL reads as empty.
i	The row.

Returns: The name, or NULL past the end.

◆ wa_scan_read_ok()

bool wa_scan_read_ok	(	uint32_t	status,
		unsigned	reported,
		bool	read_ok,
		unsigned	read,
		unsigned	room )

Whether a scan reported done counts as done.

The read holds what the report counts, or fills the buffer when the report counts more than fit.

Parameters

status	The done report's status: 0 success, other a failure.
reported	The networks the done report counts.
read_ok	The list was read (esp_wifi_scan_get_ap_records()).
read	The networks read.
room	The records the read had room for.

Returns: true for a status of 0 and read equal to the smaller of reported and room.

◆ wa_scan_refused()

bool wa_scan_refused	(	wa_t *	w,
		uint32_t	tok )

The radio refused to start the scan of tok: off WA_OFF_FAILED when it is the scan under way.

Parameters

w	The session.
tok	The scan's token.

Returns: Whether the session ended; false for a scan no longer under way.

◆ wa_secret_make()

void wa_secret_make	(	char	out[WA_SECRET_LEN+1u],
		wa_rand_fn	rand,
		void *	ctx )

WA_SECRET_LEN characters of WA_SECRET_CHARS and a terminator, each drawn evenly from the alphabet (words that would favour some characters are drawn again).

Parameters

out	Receives the secret.
rand	The source of random words.
ctx	Passed to `rand`.

◆ wa_serving()

bool wa_serving ( const wa_t * w )

Whether the page is being served.

Parameters

w	The session.

Returns: true with the access point up or joined, not for WA_MODE_FETCH.

◆ wa_start()

wa_off_t wa_start	(	wa_t *	w,
		wa_mode_t	mode,
		wa_off_t	gate,
		uint32_t	now_ms,
		wa_rand_fn	rand,
		void *	ctx )

Start in mode when gate is WA_OFF_NONE, with a fresh password and code.

A start while the radio runs ends that session first.

Parameters

w	The session.
mode	What the session is for.
gate	wa_gate()'s answer.
now_ms	Now.
rand	The source of the secrets.
ctx	Passed to `rand`.

Returns: WA_OFF_NONE, and the platform brings the radio up; otherwise the reason, and the radio stays off.

◆ wa_tick()

bool wa_tick	(	wa_t *	w,
		uint32_t	now_ms,
		wa_off_t	gate,
		bool	stop )

Once a frame: the gate, STOP and the time-outs. Off, a gate or STOP ends a linger (wa_lingers()).

Parameters

w	The session.
now_ms	Now.
gate	wa_gate()'s answer.
stop	STOP pressed since the last call.

Returns: Whether this call switched the session off or ended its linger.

◆ wa_unlinger()

void wa_unlinger ( wa_t * w )

The platform needs the radio off now: a linger ends; a session that runs goes on.

Parameters

w	The session.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ WA_ADDRESS_MS

◆ WA_AUTH_TRIES

◆ WA_GUESS_MAX

◆ WA_IDLE_MS

◆ WA_JOIN_MS

◆ WA_NAME_MAX

◆ WA_SECRET_CHARS

◆ WA_SECRET_LEN

◆ WA_START_MS

Typedef Documentation

◆ wa_rand_fn

Enumeration Type Documentation

◆ wa_code_t

◆ wa_conf_err_t

◆ wa_join_err_t

◆ wa_mode_t

◆ wa_off_t

◆ wa_scan_step_t

◆ wa_state_t

Function Documentation

◆ wa_close()

◆ wa_code_check()

◆ wa_conf_defaults()

◆ wa_conf_forget()

◆ wa_conf_load()

◆ wa_conf_save()

◆ wa_conf_set_net()

◆ wa_gate()

◆ wa_idle_left()

◆ wa_init()

◆ wa_lingers()

◆ wa_modes()

◆ wa_name()

◆ wa_on_address()

◆ wa_on_ap_up()

◆ wa_on_associated()

◆ wa_on_drop()

◆ wa_on_failed()

◆ wa_on_join_failed()

◆ wa_on_scan_done()

◆ wa_on_scan_end()

◆ wa_pending_change()

◆ wa_pending_done()

◆ wa_pending_due()

◆ wa_pending_forget()

◆ wa_pending_init()

◆ wa_pending_write()

◆ wa_radio()

◆ wa_request_begin()

◆ wa_request_end()

◆ wa_scan_add()

◆ wa_scan_begin()

◆ wa_scan_clear()

◆ wa_scan_is()

◆ wa_scan_pending()

◆ wa_scan_pick()

◆ wa_scan_read_ok()

◆ wa_scan_refused()

◆ wa_secret_make()

◆ wa_serving()

◆ wa_start()

◆ wa_tick()

◆ wa_unlinger()