14.11. Off-Device Communication

GEISA Application Programming Interface

GEISA allows applications to make use of two types of off-device communications: Message based, and IP socket based.

GEISA distinguishes between platform-mediated message-based communication and application-managed IP socket communication. These are separate communication mechanisms. Applications do not use GEISA app-message request and response payloads to perform IP socket communication. For ADM-conformant platforms, app-message transport uses the GEISA ADM LwM2M over CoAP path, carried by platform-controlled IP communication outside of the application execution environment. Applications remain unaware of those ADM transport details. Applications that require both mechanisms must request both in their manifest, and platforms enforce each according to the approved deployment policy.

14.11.1. Message-based via LwM2M

This type of communication is available on every device with Application & Device Management and uses the administrative LwM2M connection for transport.

This type of communication is bi-directional and messages may be sent unsolicited by either side. Messages may be sent by an Edge Application or delivered to an Edge Application.

Applications use the message bus to send and receive these messages to/from the platform which in turn makes use of LwM2M to transport them. The applications themselves are unaware of any LwM2M details.

Delivery of messages under some circumstances may be significantly delayed or lost. Queue responsibility depends on the direction of the message.

For messages sent by an Edge Application through /3600 Client to Server, the ADM-conformant Platform is responsible for retaining accepted messages while delivery to the EMS is temporarily unavailable. The Platform remains responsible until the message is delivered to the EMS, expires, or reaches an applicable retention limit. Accepted messages SHALL be persistent across device reboots, power cycles, or application restarts. If a message cannot be delivered, a failure status is reported to the sender.

Note

GEISA does not currently define interoperable configuration for message queue depth, maximum retention time, retry behavior, or other queue limits. Implementations may provide operator-configured limits for these values. This may be standardized in a future version of the specification.

Platforms SHOULD avoid creating a burst of delayed traffic when connectivity is restored. Appropriate mechanisms may include message expiration, priority handling, backoff, rate limiting, queue limits, or other platform-controlled delivery controls.

A message-specific time-to-live value, when present, indicates the sender’s requested maximum useful lifetime for that message. The platform MAY apply an implementation-defined maximum queued-message retention period and SHOULD expire the message when either the applicable time-to-live or retention period is reached.

Note

This version of the specification does not define an interoperable operator override mechanism for storm conditions, network congestion, FAN outages, or other traffic management events. Such controls may exist as platform-specific or operator-specific capabilities and may be defined in a future version of this specification.

This version of the specification does not mandate fallback or transfer of queued messages across destination classes or communication mechanisms. For example, a platform is not required to transfer queued message-based communication to an application IP socket communication path, or to transfer failed application IP socket communication to message-based communication. Applications that require cross-mechanism fallback are responsible for implementing that behavior within the permissions approved by the deployment policy.

For messages being delivered to an Edge Application through /3600 Server to Client, the EMS is responsible for retaining an accepted message while the target Platform is unavailable. After the Platform accepts the message, the Platform is responsible for delivery to the Edge Application. If the application is not running or does not acknowledge delivery over the message bus, the Platform retains the message according to the applicable TTL and retention policy and reports a failure status to the sender if delivery fails.

If an application is uninstalled while its messages are in the queue, or if messages are received for an application that is not installed, a delivery failure status SHALL be reported to the sender for each queued message, and the queue then purged.

Note

Messages sent by an Edge Application are made available through configured Data Distribution targets as required by Data Distribution. Subject to operator policy, the System Operator or an authorized Vendor Application Server MAY also initiate messages to an Edge Application.

GEISA Pyramid

14.11.2. IP Socket Based Communications

Applications can also make use of traditional IP socket based real-time communications on devices equipped with cellular, Wi-Fi, or other IP connectivity. Applications MUST specify the endpoints they need to communicate to (IP/Port) in their Application Deployment Manifest so that those policies can be approved by operators and implemented in the platform using firewall rules.

Conformant platform implementations MUST provide an IP socket based interface to authorized Applications; however, in any given environment, applications may or may not be able to successfully communicate over IP. Application designers should consider carefully the challenges of local IP communications and design their applications to robustly handle limited or intermittent communications.

Applications MUST also specify the expected volume of data per day per destination class.

Once a network interface is online, the Application may use outbound-initiated AF_INET/AF_INET6 sockets from within the AII environment to reach the specified endpoints.

Approval of IP socket communication does not imply unmanaged or application-selected network reachability. The System Operator remains authoritative for which destination classes, endpoints, protocols, ports, and volumes are allowed. Platform implementations MAY satisfy approved IP socket communication using direct routing, NAT, firewall rules, forwarding, transparent proxies, shared upstream connections, or other platform-controlled mechanisms, provided that authorized Applications can use standard socket APIs from within the execution environment and the approved policy is locally enforced. Implementations which require traffic to route through an external proxy prior to reaching their destination network are not conformant.

Regardless of the platform mechanism used, the Application remains responsible for its application-layer security behavior. The operator remains responsible for the deployment policy, operator-managed trust configuration, and operation of operator-managed platform and EMS components. See Security considerations below.

Inbound-initiated connections towards the Application are only supported for the local destination class defined below and disallowed from other destination classes.

Note

Not all destination classes may be available in a given GEISA device or deployment. An operator or device manufacturer may only support a subset depending on capabilities, deployment architecture, or security policy. The availability of an approved application IP communication path is not guaranteed. Applications may encounter intermittent or prolonged outages, or may run on devices where some or all destination classes are not provisioned. Applications approved for IP socket communication SHOULD be designed to handle these conditions, operate in a degraded mode where appropriate, avoid producing excessive alarms or logs, and fall back to message-based communication only when that behavior is implemented by the application and allowed by deployment policy.

Note

Regardless of whether applications are authorized to use direct IP socket communications, ADM-conformant platforms still require IP connectivity for the ADM LwM2M over CoAP path. Platform-managed IP connectivity is distinct from Application-managed IP socket access.

GEISA Pyramid

14.11.3. Interface Types

The method of connectivity that a device provides can vary from a home Wi-Fi device (e.g. router) providing Internet connectivity, to private Wi-Fi for partner integrations, or to a variety of operator-maintained connectivity options such as shared Wi-Fi hotspots, cellular, mesh, wired, or proprietary interfaces.

Applications need to know which of these are available (may be multiple or none) and online for use at any given time; however, enumerating both the technology and the allowable use cases that they can transport can become complex quickly.

Example types of network interfaces:

  • Wi-Fi - Home (device is client)

  • Wi-Fi - Meter (device is AP)

  • Wi-Fi - Operator/Partner-Hotspot (device is client)

  • Cellular - Internet APN

  • Cellular - Private APN

  • Ethernet - Home

  • Ethernet - Private/Partner Devices

  • Field Area Network

Other network interfaces that may be available (but out of scope of IP socket-based communication in GEISA at this time) are:

  • Bluetooth / Bluetooth LE

  • IoT integrations via 802.15.4 technologies (Zigbee, Thread, etc.)

  • Other wired connectivity or peripherals: RS232/485, USB connected devices, etc.

This version of the specification defines two interfaces types:

  • HAN

  • FAN

HAN is inclusive of all local network interfaces, though this is most likely to be a Wi-FI interface. Only one local interface is supported.

FAN is inclusive of all operator network interfaces. This is likely to be either cellular or mesh technologies for AMI meters, though it may be powerline carrier (PLC) or satellite for some devices. Only one operator network interface is supported. For devices which have multiple operator network interfaces and can switch between them (e.g. dual-radio devices), the FAN interface is assumed to be the presently active FAN technology.

Note

New interface types may be added in future versions of this specification.

GEISA Pyramid

14.11.4. Destination Classes

The device may have zero, one, or multiple interfaces online at any given time. Applications are not required to know these details but instead only need to know if their desired endpoints are accessible under the approved deployment policy and what volume limits are in place.

Each endpoint an application defines falls into one of these categories:

  • Internet Endpoint (ex: Public Cloud)

  • Operator Endpoint (ex: Private Cloud)

  • Local Endpoint (something off-device, but on-net and private)

  • Message based (LwM2M)

For each of these classes, applications have a defined volume limit for when that class is metered. In typical deployments, the platform will associate Internet and Local classes to the device’s HAN interface and the Operator class to the device’s FAN interface; however, other combinations are possible.

GEISA Pyramid

14.11.5. Network State

For each destination class, applications have a network state that informs the application if and what volume of communication is available as described in Platform and App Status.

An application can request communication with more than one class of endpoint and would need a network status indicator for each class separately. For example, it may communicate with both Internet Endpoints as well as Local Endpoints.

Applications may observe a mismatch between reported network state and their own communication attempts. This version of the GEISA specification does not define a dedicated application-to-platform diagnostic reporting mechanism. Implementations MAY expose troubleshooting, logging, or diagnostic reporting through implementation-specific mechanisms or through future GEISA status, logging, or messaging extensions.

GEISA Pyramid

14.11.6. Volume Limits

Each destination class may be metered depending on which underlying technology transports the data. A Home Wi-Fi network would normally be considered unlimited whereas a cellular connection would be metered in order to keep the device under a monthly volume limit. An operator may choose to meter application traffic even on “unlimited” connections to ensure that devices are polite guests when connected to customer networks.

An application developer MUST define volume limits per destination class in their Vendor Application Manifest. These limits may be overridden by the operator at deployment time when converting the Vendor Application Manifest into a Deployment Manifest.

These volume limits are specified as a per day (24 hour period) limit in bytes. For interoperability, application-visible volume accounting is based on application payload bytes. For IP socket communication, this is measured at the application socket boundary. For message-based communication, this is measured at the GEISA app-message payload boundary. Both transmit and receive application payload bytes count toward the application’s limit.

Operators may account for expected protocol, security, encapsulation, tunnel, or lower-layer overhead when setting limits. The platform MAY separately measure or estimate interface-level bytes, including protocol and lower-layer overhead, for operator visibility, network planning, analysis, audit, and subsequent adjustment of limits.

The daily rollover mechanism and reset period are deployment and platform policy. This version of the specification does not define an application-visible transaction for configuring those policy values. The application obtains the remaining volume limits and the next reset time via Platform and App Status. ADM transactions are defined for allowing an EMS to monitor an applications consumption and to adjust limits if needed, via the LwM2M 3602 GEISA Application Accounting object. Please see Application & Device Management for discussion.

If an application exhausts its metered volume quota for one or more destination classes, the policy for those classes remains metered and the remaining metered byte count is reported as zero until the next reset or operator adjustment. Exhaustion of a metered quota does not change the policy to zero.

The zero policy indicates that the Application currently has no usable allocation for that destination class, such as where access is not approved by deployment policy. Volume limits do not apply to destination classes when the policy is unlimited.

GEISA Pyramid

14.11.7. Security considerations

For message based communications, the operating environment will provide encryption and authentication for data passed between the device and head-end via LwM2M, applications MAY perform further encryption and/or authentication on top of what Application & Device Management provides.

For IP socket based communications, the application is responsible for encryption and authentication of data passed between the device and its endpoints where needed.

Applications MUST NOT assume that approved IP socket communication provides the same security, queuing, retry, or store-and-forward behavior as GEISA message-based communication unless those behaviors are explicitly provided by the application protocol or deployment environment.

When a platform uses proxying, forwarding, NAT, tunneling, or shared upstream connectivity, application-layer security remains the responsibility of the relevant communication design. Network-layer mediation SHALL preserve end-to-end application TLS or mTLS semantics. Applications MAY use certificate pinning, client authentication, or other application-layer trust mechanisms where supported by their protocol.

Note

This version of the specification does not define an interoperable mechanism for an Application vendor to declare whether TLS inspection, explicit proxying, or operator-mediated re-origination of application-layer security is supported. Operators and platform implementations that use such mechanisms are responsible for ensuring that the behavior is compatible with the Application, its configured trust material, and the deployment policy. A future version may define manifest fields or policy controls for this behavior.

Note

Please see Network Security for details on deployment manifest security settings for network access.

GEISA Pyramid

14.11.8. Connectivity

The operating environment is responsible for providing network connectivity between each AII environment and network interfaces.

The platform is responsible for implementing policy (by firewall and forwarding rules), accounting (volume limits), and providing underlying connectivity and routing between these components.

Note

GEISA does not mandate a specific technology that the implementer of the operating environment must use to accomplish this, but does recommend the use of Linux network namespaces, veth interfaces, and iptables/nftables for filtering, NAT, and accounting on LEE platform implementations GEISA Linux Execution Environment. The implementer may also make use of on-device transparent proxies if desired, however the Application must be able to use AF_INET/AF_INET6 sockets from within the AII environment with any encoding and protocol within.

The operating environment MUST provide a local lo interface within the AII environment for each application, even when off-device IP communication is not requested or approved. The local lo interface must be up and configured with both 127.0.0.1 and ::1 addresses.

The apparent address, route, or connection path visible to an Application inside its AII environment is not required to correspond one-to-one with the physical interface, upstream session, or operator network path used by the platform. Applications should treat the socket interface as the approved local execution-environment abstraction and rely on Platform and App Status for communication availability and quota state.

GEISA Pyramid

14.11.9. Policy Rules

The Application Manifests include a set of Endpoints the Application is expecting to communicate with. The application must list every endpoint that it wishes to communicate with per destination class. See Network Security for discussion of network access tuples.

GEISA Pyramid

14.11.10. DNS

Applications must be able to reach DNS services from within the AII environment by using standard libraries. Platforms MUST provide a local DNS implementation that applications can query using conventional calls (e.g. gethostbyname() or getaddrinfo()); however, there is no guarantee that the deployed environment or accessible network interface offers DNS services. Therefore, applications should fallback gracefully if DNS resolution fails or the application itself may fail.

Platforms are not required to support mDNS or DNS-SD in this version of the specification. While applications MAY attemt to use DNS, applications which depend on DNS will fail to operate correctly in deployments that do not provide DNS support.

While policy rules are defined using IP addresses, Applications may use DNS queries to avoid hard-coded IP literals within their application source or configuration files, but applications should not assume that name resolution will be successful in all environments.

Platforms SHOULD implement a caching local resolver that honors TTL to reduce network traffic off-device due to repeated application lookups for the same name.

DNS in a multi-tenant and multi-interface environment can get quite complex. For example, an operator may implement their Operator Endpoints using a dedicated private TLD and configure the resolver to direct DNS lookups for that TLD over their private network where other TLDs for Internet Endpoints use a home Wi-Fi or Internet-connected Cellular provider’s supplied DNS.

GEISA Pyramid

14.11.11. Local Endpoint Considerations

Local Endpoints are defined to allow an Application access to local resources on a connected network. Typically this would be for purposes of local device integrations such as EVSE, Solar Inverter and battery storage equipment, smart plugs and similar devices. This class is typically only available for devices that are connected to a home or Meter hosted Wi-Fi, or wired connection, for example.

Unlike the operator and Internet destination classes, the local destination class allows additional functionality:

  • Inbound access, including multicast and broadcast

  • Outbound multicast and broadcast

As the IP addressing of the connected network are not known and not static between devices, the Application Manifest cannot list destination/source IP addresses for policy rules, but instead only protocol/port and multicast groups.

An application requesting inbound access in its manifest requires that the platform create that inbound mapping from the appropriate local interface (such as a WiFi interface) into the AII environment. When requesting a port mapping, both IPv4 and IPv6 MUST be mapped if the local interface supports both.

Many common local device protocols use multicast or broadcast for discovery and registration. Applications with access to a Local interface, SHOULD be able to both send to IP multicast groups and register IP multicast groups for receipt on that interface. If specified in the application manifest, the platform SHALL register those addresses on the appropriate local interface and forward received packets that match both the multicast/broadcast address and the inbound protocol/port into the AII environment.

Multiple applications MAY register the same IP multicast group at the same time; however, they MUST NOT register the same protocol/port. The platform and/or ADM system MUST arbitrate inbound protocol/port requests in each application manifest to prevent multiple applications from requesting the same inbound protocol/port combination.

14.11.11.1. MQTT Details

  • QoS: 1 / Acknowledged R/R

  • Req Topic: geisa/api/message/upstream/req/<userid>

  • Rsp Topic: geisa/api/message/upstream/rsp/<userid>

  • Req Topic: geisa/api/message/downstream/req/<userid>

  • Rsp Topic: geisa/api/message/downstream/rsp/<userid>

Note

In the topic definitions, <userid> refers to the platform-local identifier of the requesting GEISA application instance (see Glossary for additional information).

14.11.11.2. API Permissions

  • Application:

    • Publish: geisa/api/message/upstream/req/<userid>

    • Publish: geisa/api/message/downstream/rsp/<userid>

    • Subscribe: geisa/api/message/upstream/rsp/<userid>

    • Subscribe: geisa/api/message/downstream/req/<userid>

  • Platform:

    • Wildcard Subscribe: geisa/api/message/upstream/req/#

    • Wildcard Subscribe: geisa/api/message/downstream/rsp/#

    • Publish: geisa/api/message/upstream/rsp/<userid>

    • Publish: geisa/api/message/downstream/req/<userid>

14.11.11.3. Transaction Data

GEISA Pyramid