gps: Rework the CLI

- more consistency with other cli commands
- new format for gps fix
- gps format accepts postfix (s/m/d/h)
- documentation
This commit is contained in:
Florent committed 2026-11-08 08:47:35 -04:00
1 parent c06def2f41
commit 6c9600e1e7
7 files changed
+110 -54

No files matched your search

+23 -4
View File
@@ -1021,10 +1021,10 @@ region save
#### View or change the GPS acquisition period
**Usage:**
- `gps period`
- `gps period <seconds>`
- `gps period <value>`
**Parameters:**
- `seconds`: `0` for continuous tracking, or `1`-`86400` for periodic acquisition
- `value`: `0` for continuous tracking, or a period. The value can be postfixed with `s`, `m`, `h` or `d` to specify the unit (seconds by default).
**Note:** A periodic acquisition stops after receiving a valid fix, then resumes after the configured period.
@@ -1034,7 +1034,12 @@ region save
**Usage:**
- `gps fix`
**Note:** Returns the last valid latitude, longitude, altitude, and elapsed time since the fix. Returns `no fix` until a valid fix is received.
**Output:**
- `> Fix (n sat): <lat>, <lon>`: the GPS currently has a fix.
- `> Last fix <age> ago (n sat)[, acq <time>]: <lat>, <lon>`: position of the last valid fix; `acq` is shown only while the receiver is running and shows how for how long the gps has been trying to get a fix.
- `> No fix[, acq <time>]`: no valid fix since the node started.
**Note:** Ages and durations are given in `s`, `m` or `h`.
---
@@ -1044,11 +1049,25 @@ region save
---
#### On demand GPS fix
**Usage:**
- `gps once`
- `gps once -s`
**Parameters:**
- `-s`: also sync this node's clock with GPS time (as `gps sync`)
**Note:** Starts an acquisition now. If the GPS is off, it is switched and kept on until a valid fix and then turned off.
**Reply:** `OK - turning on and acquiring` (GPS was off), `OK - waking gps` (periodic mode, receiver off between acquisitions) or `OK - gps already on`. `Error, gps hw switch off` if a hardware GPS switch is off, `Error, gps once not supported`.
---
#### View GPS time to first fix statistics
**Usage:**
- `gps fix_stats`
**Output:** `ttf:<last>/<max> ok:<n> miss:<n>`: last and maximum time between a start of the GPS and its first valid fix, then the last count of consecutive starts with a fix (`ok`) or without one (`miss`).
**Output:** `> ttf:<last>/<max> ok:<n> miss:<n>`: last and maximum time between a start of the GPS and its first valid fix, then the last count of consecutive starts with a fix (`ok`) or without one (`miss`).
---
+23 -4
View File
@@ -142,10 +142,10 @@ Radio parameters are common to all roles and handled by `CommonRadioPrefs`.
#### View or change the GPS acquisition period
**Usage:**
- `gps period`
- `gps period <seconds>`
- `gps period <value>`
**Parameters:**
- `seconds`: `0` for continuous tracking, or `1`-`86400` for periodic acquisition
- `value`: `0` for continuous tracking, or a period. The value can be postfixed with `s`, `m`, `h` or `d` to specify the unit (seconds by default).
**Note:** A periodic acquisition stops after receiving a valid fix, then resumes after the configured period.
@@ -155,7 +155,12 @@ Radio parameters are common to all roles and handled by `CommonRadioPrefs`.
**Usage:**
- `gps fix`
**Note:** Returns the last valid latitude, longitude, altitude, and elapsed time since the fix. Returns `no fix` until a valid fix is received.
**Output:**
- `> Fix (n sat): <lat>, <lon>`: the GPS currently has a fix.
- `> Last fix <age> ago (n sat)[, acq <time>]: <lat>, <lon>`: position of the last valid fix; `acq` is shown only while the receiver is running and shows how for how long the gps has been trying to get a fix.
- `> No fix[, acq <time>]`: no valid fix since the node started.
**Note:** Ages and durations are given in `s`, `m` or `h`.
---
@@ -165,11 +170,25 @@ Radio parameters are common to all roles and handled by `CommonRadioPrefs`.
---
#### On demand GPS fix
**Usage:**
- `gps once`
- `gps once -s`
**Parameters:**
- `-s`: also sync this node's clock with GPS time (as `gps sync`)
**Note:** Starts an acquisition now. If the GPS is off, it is switched and kept on until a valid fix and then turned off.
**Reply:** `OK - turning on and acquiring` (GPS was off), `OK - waking gps` (periodic mode, receiver off between acquisitions) or `OK - gps already on`. `Error, gps hw switch off` if a hardware GPS switch is off, `Error, gps once not supported`.
---
#### View GPS time to first fix statistics
**Usage:**
- `gps fix_stats`
**Output:** `ttf:<last>/<max> ok:<n> miss:<n>`: last and maximum time between a start of the GPS and its first valid fix, then the last count of consecutive starts with a fix (`ok`) or without one (`miss`).
**Output:** `> ttf:<last>/<max> ok:<n> miss:<n>`: last and maximum time between a start of the GPS and its first valid fix, then the last count of consecutive starts with a fix (`ok`) or without one (`miss`).
---
+6 -6
View File
@@ -358,7 +358,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re
_prefs->node_lat = _sensors->node_lat;
_prefs->node_lon = _sensors->node_lon;
savePrefs();
strcpy(reply, "ok");
strcpy(reply, "OK");
} else if (memcmp(command, "gps advert", 10) == 0) {
if (strlen(command) == 10) {
switch (_prefs->advert_loc_policy) {
@@ -372,22 +372,22 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re
strcpy(reply, "> share");
break;
default:
strcpy(reply, "error");
strcpy(reply, "Error, invalid policy");
}
} else if (memcmp(command+11, "none", 4) == 0) {
_prefs->advert_loc_policy = ADVERT_LOC_NONE;
savePrefs();
strcpy(reply, "ok");
strcpy(reply, "OK");
} else if (memcmp(command+11, "share", 5) == 0) {
_prefs->advert_loc_policy = ADVERT_LOC_SHARE;
savePrefs();
strcpy(reply, "ok");
strcpy(reply, "OK");
} else if (memcmp(command+11, "prefs", 5) == 0) {
_prefs->advert_loc_policy = ADVERT_LOC_PREFS;
savePrefs();
strcpy(reply, "ok");
strcpy(reply, "OK");
} else {
strcpy(reply, "error");
strcpy(reply, "Error, invalid policy");
}
#endif
} else if (memcmp(command, "powersaving on", 14) == 0) {
+49 -40
View File
@@ -41,13 +41,13 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
LocationProvider* location = sensors.getLocationProvider();
char mode[32];
if (getGpsPeriod() == 0) {
strcpy(mode, "tracking");
strcpy(mode, "continuous");
} else {
snprintf(mode, sizeof(mode), "periodic (%lus)",
(unsigned long)getGpsPeriod());
}
if (location == nullptr) {
strcpy(reply, "gps provider not found");
strcpy(reply, "Error, gps provider not found");
} else if (location->isGpsOn()) {
const char* activity = "active";
if (!location->isActive()) {
@@ -67,33 +67,38 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
} else {
strcpy(fix, "no fix");
}
snprintf(reply, 160, "on, %s, %s, mode: %s", activity, fix, mode);
snprintf(reply, 160, "> on, %s, %s, %s", activity, fix, mode);
} else {
snprintf(reply, 160, "off, mode: %s", mode);
snprintf(reply, 160, "> off, %s", mode);
}
return true;
}
if (strcmp(command, "gps fix") == 0) {
LocationProvider* location = sensors.getLocationProvider();
char acq[16] = "";
if (location == nullptr) {
strcpy(reply, "gps provider not found");
} else if (!location->hasValidFix()) {
strcpy(reply, "no fix");
strcpy(reply, "Error, gps provider not found");
return true;
}
if (location->isActive()) {
char t[12];
formatDuration(t, sizeof(t), location->getAcquisitionAge());
snprintf(acq, sizeof(acq), "acq %s", t);
}
if (!location->hasValidFix()) {
snprintf(reply, 160, "> No fix%s%s", acq[0] ? ", " : "", acq);
} else {
const long latitude = location->getLatitude();
const long longitude = location->getLongitude();
const uint32_t fixAge = location->getLastFixAge();
char age[24];
if (fixAge == UINT32_MAX) {
strcpy(age, "age unavailable");
char pos[40];
snprintf(pos, sizeof(pos), "%.6f, %.6f", latitude / 1e6, longitude / 1e6);
if (location->isValid()) {
snprintf(reply, 160, "> Fix (%d sat): %s", location->satellitesCount(), pos);
} else {
snprintf(age, sizeof(age), "%lus ago", (unsigned long)fixAge);
char age[12];
formatDuration(age, sizeof(age), location->getLastFixAge());
snprintf(reply, 160, "> Fix %s ago (%d sat)%s%s: %s", age, location->satellitesCount(),acq[0] ? ", " : "", acq, pos);
}
snprintf(reply, 160, "%s%ld.%06ld, %s%ld.%06ld, %ldm, %s",
latitude < 0 ? "-" : "", labs(latitude) / 1000000L,
labs(latitude) % 1000000L,
longitude < 0 ? "-" : "", labs(longitude) / 1000000L,
labs(longitude) % 1000000L, location->getAltitude() / 1000L, age);
}
return true;
}
@@ -101,12 +106,12 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
LocationProvider* location = sensors.getLocationProvider();
if (location == nullptr) {
strcpy(reply, "gps provider not found");
strcpy(reply, "Error, gps provider not found");
return true;
}
if (location->hasHardwareEnableState() && !location->isHardwareEnabled()) {
strcpy(reply, "gps hw switch off");
strcpy(reply, "Error, gps hw switch off");
return true;
}
@@ -117,26 +122,26 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
: "gps already on";
if (location->startOnce()) {
snprintf(reply, 160, "ok (%s)", state);
snprintf(reply, 160, "OK - %s", state);
} else {
strcpy(reply, "gps once not supported");
strcpy(reply, "Error, gps once not supported");
}
return true;
}
if (memcmp(command, "gps on", 6) == 0) {
if (!setGpsEnabled(sensors, true)) {
strcpy(reply, "gps toggle not found");
strcpy(reply, "Error, gps toggle not found");
} else {
strcpy(reply, "ok");
strcpy(reply, "OK");
}
return true;
}
if (memcmp(command, "gps off", 7) == 0) {
if (!setGpsEnabled(sensors, false)) {
strcpy(reply, "gps toggle not found");
strcpy(reply, "Error, gps toggle not found");
} else {
strcpy(reply, "ok");
strcpy(reply, "OK");
}
return true;
}
@@ -149,34 +154,38 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
return true;
}
if (memcmp(command, "gps period ", 11) == 0) {
char* end = nullptr;
char* end;
unsigned long period = strtoul(command + 11, &end, 10);
if (command[11] == '\0' || *end != '\0' || period > 86400) {
strcpy(reply, "gps period must be 0-86400 seconds");
unsigned long mult = 1;
if (*end == 'm') mult = 60;
else if (*end == 'h') mult = 3600;
else if (*end == 'd') mult = 86400;
if (mult > 1 || *end == 's') end++; // skip the suffix char
if (command[11] == '\0' || *end != '\0') {
strcpy(reply, "Error, invalid gps period");
} else if (!setGpsPeriod(sensors, (uint32_t)(period * mult)) ||
!setGpsEnabled(sensors, true)) {
strcpy(reply, "Error, gps provider not found");
} else {
if (!setGpsPeriod(sensors, (uint32_t)period) ||
!setGpsEnabled(sensors, true)) {
strcpy(reply, "gps provider not found");
} else {
strcpy(reply, "ok");
}
strcpy(reply, "OK");
}
return true;
}
if (memcmp(command, "gps sync", 8) == 0) {
LocationProvider* location = sensors.getLocationProvider();
if (location == nullptr) {
strcpy(reply, "gps provider not found");
strcpy(reply, "Error, gps provider not found");
} else {
location->syncTime();
strcpy(reply, "ok");
strcpy(reply, "OK");
}
return true;
}
if (strcmp(command, "gps fix_stats") == 0) {
LocationProvider* location = sensors.getLocationProvider();
if (location == nullptr) {
strcpy(reply, "gps provider not found");
strcpy(reply, "Error, gps provider not found");
} else {
const LocationProvider::FixStats s = location->getFixStats();
char last[12] = "-", max[12] = "-";
@@ -184,7 +193,7 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
formatDuration(last, sizeof(last), (s.lastTtffMs + 500) / 1000);
formatDuration(max, sizeof(max), (s.maxTtffMs + 500) / 1000);
}
snprintf(reply, 160, "ttf:%s/%s ok:%lu miss:%lu", last, max,
snprintf(reply, 160, "> ttf:%s/%s ok:%lu miss:%lu", last, max,
(unsigned long)s.consecutiveFixes, (unsigned long)s.consecutiveMisses);
}
return true;
@@ -192,9 +201,9 @@ bool CommonGpsPrefs::handleCommand(const char* command, SensorManager& sensors,
if (strcmp(command, "gps diag") == 0) {
LocationProvider* location = sensors.getLocationProvider();
if (location == nullptr) {
strcpy(reply, "gps provider not found");
strcpy(reply, "Error, gps provider not found");
} else {
int prefix = snprintf(reply, 160, "req:%u ", isGpsEnabled() ? 1U : 0U);
int prefix = snprintf(reply, 160, "> req:%u ", isGpsEnabled() ? 1U : 0U);
if (prefix >= 0 && prefix < 160) location->formatDiagnostics(reply + prefix, 160 - prefix);
}
return true;
+1
View File
@@ -86,6 +86,7 @@ public:
virtual bool hasHardwareEnableState() const { return false; }
virtual bool isHardwareEnabled() const { return true; }
virtual bool isGpsOn() const { return _gpsOn; }
virtual uint32_t getAcquisitionAge() const { return 0; }
virtual bool startOnce() { return false; }
virtual void setGpsOn(bool on) {
_gpsOn = on;
@@ -175,6 +175,10 @@ public:
return _gpsPeriodSeconds;
}
uint32_t getAcquisitionAge() const override {
return (uint32_t)(millis() - _acquisitionStarted) / 1000UL;
}
bool startOnce() override {
if (_gpsOn) { // already on, acquire now
_nextAcquisition = millis();
@@ -194,6 +194,10 @@ public:
return _useI2c ? _gpsOn : _nmea.isGpsOn();
}
uint32_t getAcquisitionAge() const override {
return _useI2c ? (uint32_t)(millis() - _acquisitionStarted) / 1000UL : _nmea.getAcquisitionAge();
}
bool startOnce() override {
return _useI2c ? false : _nmea.startOnce(); // not supported on the RAK12500
}