ota_version.h File Reference

Dotted version comparison, for deciding whether an update goes forwards or backwards. More...

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

Include dependency graph for ota_version.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	OTA_VERSION_PARTS   4U
	Numeric components compared; the rest of the string is ignored.
#define	OTA_VERSION_MAX   32U
	Longest version string looked at, matching esp_app_desc_t::version.
#define	OTA_VERSION_SHOWN_MAX   (OTA_VERSION_MAX + 2U)
	Bytes needed by ota_version_display: the version, a 'v', a NUL.

Functions
static void	ota_version_parse (const char *s, unsigned long out[OTA_VERSION_PARTS])
	Read up to OTA_VERSION_PARTS dotted numbers out of s.
static int	ota_version_cmp (const char *a, const char *b)
	Order two version strings.
static const char *	ota_version_display (const char *v, char *buf, size_t n)
	The display form of a version: 1.0.0 reads as v1.0.0 on screen.

Detailed Description

Dotted version comparison, for deciding whether an update goes forwards or backwards.

Header-only and free of ESP-IDF dependencies on purpose, the same reason form_parse.h is: the answer decides what the panel tells the operator before they replace the firmware on a terminal that signs transactions, and a downgrade that gets announced as an upgrade is the failure that matters. Kept where a host test can reach it (tests/units/test_ota_version.cpp).

Deliberately NOT semver. Build metadata, pre-release tags and git describe suffixes are ignored rather than ordered — "1.2.3-rc1" compares equal to "1.2.3". Ordering release candidates is not a decision this device needs to make, and the operator confirms every install on the panel regardless.

Definition in file ota_version.h.

Macro Definition Documentation

OTA_VERSION_MAX

#define OTA_VERSION_MAX   32U

Longest version string looked at, matching esp_app_desc_t::version.

Definition at line 35 of file ota_version.h.

Referenced by ota_commit(), ota_end(), and ota_version_parse().

OTA_VERSION_PARTS

#define OTA_VERSION_PARTS   4U

Numeric components compared; the rest of the string is ignored.

Definition at line 32 of file ota_version.h.

Referenced by ota_version_cmp(), and ota_version_parse().

OTA_VERSION_SHOWN_MAX

#define OTA_VERSION_SHOWN_MAX   (OTA_VERSION_MAX + 2U)

Bytes needed by ota_version_display: the version, a 'v', a NUL.

Definition at line 104 of file ota_version.h.

Referenced by build_ota_confirm(), build_settings(), and pos_boot().

Function Documentation

ota_version_cmp()

int ota_version_cmp ( const char * a, const char * b )

inlinestatic

Order two version strings.

Parameters

[in]	a	Left version.
[in]	b	Right version.

Returns

<0 if a is older than b, 0 if they name the same release, >0 if a is newer.

Definition at line 90 of file ota_version.h.

References ota_version_parse(), and OTA_VERSION_PARTS.

Referenced by ota_end().

ota_version_display()

const char * ota_version_display ( const char * v, char * buf, size_t n )

inlinestatic

The display form of a version: 1.0.0 reads as v1.0.0 on screen.

Prefixes only a version that starts with a digit, which leaves alone both the ? shown before a version is known and a git describe tag that already carries its own v — neither wants a second one.

Display only. What is stored, compared by ota_version_cmp, and reported in the config page's JSON stays bare, so the v cannot leak into a version comparison or into something parsing the API.

Parameters

[in]	v	Version string, may be NULL.
[out]	buf	Destination, at least OTA_VERSION_SHOWN_MAX bytes.
	n	Size of buf.

Returns

buf, or "" if buf is unusable.

Definition at line 122 of file ota_version.h.

Referenced by build_ota_confirm(), build_settings(), and pos_boot().

ota_version_parse()

void ota_version_parse ( const char * s, unsigned long out[OTA_VERSION_PARTS] )

inlinestatic

Read up to OTA_VERSION_PARTS dotted numbers out of s.

Skips one optional leading 'v'/'V'. Stops at the first character that is neither a digit nor a dot, so "1.2.3-rc1" and "1.2.3+deadbeef" both yield {1,2,3,0}. Absent components read as 0, which is what makes "1.2" and "1.2.0" compare equal.

Parameters

[in]	s	Version string, NUL-terminated.
[out]	out	Array of OTA_VERSION_PARTS components.

Definition at line 48 of file ota_version.h.

References OTA_VERSION_MAX, and OTA_VERSION_PARTS.

Referenced by ota_version_cmp().