lf-edge · OhmSpectator · Sep 18, 2025 · Aug 13, 2025
@@ -0,0 +1,128 @@
+# Local Profile Server (LPS)
+
+The **Local Profile Server (LPS)** is an optional component in the EVE ecosystem.
+It provides a way to perform **local control operations** on an EVE device — operations
+that are more practical to manage locally than through the cloud controller.
+
+Unlike the **Local Operator Console (LOC)**, which substitutes the cloud controller in
+**air-gapped deployments** and manages the **entire device configuration (EdgeDevConfig)**,
+the LPS only **complements** the controller.
+
+- **LPS scope:** limited to local, operational commands (e.g., radio silence, app restarts,
+                 graceful shutdown).
+- **LOC scope:** full device config management when the cloud is unreachable, but it can
+                 also **carry LPS-style operations** inside the `CompoundConfig` message.
+                 This message combines the full device configuration with optional local
+                 operational commands (the same format of command payloads as used for LPS).
+
+## Purpose and Capabilities
+
+The LPS typically runs as an **application deployed on the same edge node** that it manages.
+However, it may also run externally. Its role is to:
+
+- Periodically **receive state reports** from the device for:
+  - Radio devices (e.g., WiFi, cellular modems)
+  - Application instances
+  - Edge device information (onboarding, status, maintenance mode, etc.)
+  - Location data
+
+- Override the global profile with a **local profile**, thereby controlling which apps are active.
+  - Each app can be optionally configured with a set of profiles.
+  - If the currently active profile is included **and** the controller has set `Activate=true`,
+    the app will run.
+  - If `Activate=false` in the controller config, the app will remain disabled regardless
+    of the profile match.
+
+- **Trigger local operational commands**, such as:
+  - Enabling/disabling radio devices ([Radio Silence](WIRELESS.md#radio-silence))
+  - Restarting or purging an application
+  - Rebooting or shutting down the edge node gracefully
+
+## Networking and Authentication
+
+- **Transport:** plain HTTP (HTTPS not yet supported).
+- **Default port:** `8888` (configurable).
+- **Authentication:**
+  - The controller provisions a **secret LPS token** to EVE.
+  - The same token must be configured into LPS by the operator/admin
+    (so that EVE and LPS agree on it).
+  - Whenever LPS issues a command/change request, it must **include this token**.
+  - EVE rejects any requests with a missing or invalid token.
+
+## API Endpoints
+
+LPS exposes the following REST endpoints
+(see the [formal specification](https://github.com/lf-edge/eve-api/blob/main/PROFILE.md) for full details).
+All endpoints use **HTTP POST**, except for the `local_profile` endpoint, which is accessed
+via **HTTP GET**.
+
+### 1. `/api/v1/local_profile`
+
+- **From edge-node → LPS:** HTTP **GET** request for a possible local profile override.
+- **From LPS → edge-node (response):** the **local profile override**, if configured
+  (otherwise empty / HTTP code 204).
+- **Effect:** controls which apps are activated or deactivated.
+- **Interval:** EVE polls this endpoint periodically at a rate defined by `timer.config.interval`
+  (default: 1 minute).
+
+### 2. `/api/v1/radio`
+
+- **From edge-node → LPS:** current radio state (list of wireless devices and their status + metrics).
+- **From LPS → edge-node (response):** optional **radio silence configuration**.
+- **Effect:** disable/enable radio transmission.
+- **Interval:** every 5sec (normal), throttled to every 5min if LPS responds with *404*.
+- See [Radio Silence documentation](./WIRELESS.md#radio-silence).
+
+### 3. `/api/v1/devinfo`
+
+- **From edge-node → LPS:** device info:
+  - Node UUID
+  - Edge-node state
+  - Boot time, last boot reason
+  - Maintenance mode reasons
+  - Last applied device command timestamp
+- **From LPS → edge-node (response):** optional **device command**, such as:
+  - Edge-node reboot
+  - Shutdown all applications
+  - Graceful edge-node poweroff
+  - Execute `collect-info.sh` to generate a tarball containing debug information
+    and upload it to a local datastore.
+- **Interval:** every 1min (normal), throttled to every 1h if LPS responds with *404*.
+
+### 4. `/api/v1/appinfo`
+
+- **From edge-node → LPS:** list of running app instances with:
+  - UUID, version, display name
+  - Current state
+  - Errors (if any)
+  - Last executed app command timestamp
+- **From LPS → edge-node (response):** optional **app command**, e.g.:
+  - Restart
+  - Purge
+- **Interval:** every 1min (normal), throttled to every 1h if LPS responds with *404*.
+
+### 5. `/api/v1/location`
+
+- **From edge-node → LPS:** current location obtained from a GNSS module integrated
+  in a cellular modem (standalone GNSS receivers are not supported).
+- **From LPS → device (response):** none (status-only endpoint).
+- **Interval:** triggered by zedagent when location changes (not periodic).
+
+## Implementation Notes
+
+- There is currently **no open-source production-ready implementation** of the LPS.
+- A **primitive console/file-based LPS** is available inside the
+  [eden](https://github.com/lf-edge/eden/blob/master/tests/eclient/image/pkg/main.go) test
+  framework, used for validation and development.
+
+## Summary: LPS vs LOC
+
+| Aspect                   | LPS (Local Profile Server)      | LOC (Local Operator Console)                    |
+|--------------------------|---------------------------------|-------------------------------------------------|
+| Runs on                  | Typically same edge node        | Separate non-EVE machine                        |
+| Scope                    | Local operations only           | Full device config                              |
+| Purpose                  | Complement cloud controller     | Replace cloud controller when unreachable       |
+| Controls multiple nodes? | No (single device)              | Yes (multiple devices)                          |
+| Transport                | HTTP (no TLS)                   | HTTP or HTTPS (depending on LOC implementation) |
+| Signing                  | None (only token used for auth) | Config signed by the controller                 |
+| Local ops support        | Yes                             | Yes (carried inside `CompoundConfig`)           |
@@ -98,6 +98,8 @@ nav:
           - 'Jetson Orin': 'docs/NVIDIA-ORIN.md'
           - 'Jetson Xavier NX': 'docs/NVIDIA-NX.md'
           - 'Jetson Nano': 'boards/nvidia/jetson/README.md'
+  - 'Local Control & Management':
+      - 'Local Profile Server (LPS)': 'docs/LPS.md'
   - Debugging:
       - Information: 'pkg/debug/abuild/README.md'
       - Debugging: 'docs/DEBUGGING.md'

@@ -12,10 +12,8 @@ import (
 )
 
 const (
-	// checkpointDirname - location of forcefallbackfile
 	// XXX move to locationconst.go?
-	checkpointDirname     = types.PersistDir + "/checkpoint"
-	forcefallbackFilename = checkpointDirname + "/forceFallbackCounter"
+	forcefallbackFilename = types.CheckpointDirname + "/forceFallbackCounter"
 )
 
 // handle zedagent status events to look if the ForceFallbackCounter changes

@@ -6,6 +6,7 @@ package monitor
 import (
 	"io/fs"
 	"os"
+	"reflect"
 	"regexp"
 
 	"github.com/lf-edge/eve/pkg/pillar/evetpm"
@@ -78,7 +79,7 @@ func (ctx *monitor) sendNodeStatus() {
 	nodeStatus.ZedAgentStatus = ctx.getZedAgentStatus()
 	nodeStatus.AppSummary = ctx.getAppSummary()
 
-	if ctx.lastNodeStatus != nil && *ctx.lastNodeStatus == nodeStatus {
+	if ctx.lastNodeStatus != nil && reflect.DeepEqual(*ctx.lastNodeStatus, nodeStatus) {
 		return
 	}
 	ctx.lastNodeStatus = &nodeStatus