Skip to content

Introduce Network Registers for Wi-Fi/TCP Transport - #240

Open
FrancescoNegri wants to merge 10 commits into
harp-tech:mainfrom
barbaLab:feat-tcp
Open

FrancescoNegri wants to merge 10 commits into
harp-tech:mainfrom
barbaLab:feat-tcp

Conversation

@FrancescoNegri

Copy link
Copy Markdown

Overview

Up to version 1.13, the Harp protocol relied exclusively on the USB transport layer for communication between the Controller and the Device. The need to support additional transport layers arises from extending the Harp protocol to the ESP32 family of boards, which natively support Wi-Fi and TCP networking. This branch therefore introduces the network registers (R_NET_SSID, R_NET_PASSWORD, R_NET_ENDPOINT, and R_NET_CONFIG), providing the building blocks for a Wi-Fi and outbound TCP network transport layer.

Register Overview

R_NET_SSID (U8 Array) – Wi-Fi SSID

Address 020, length 32 bytes. Stores the Wi-Fi station SSID as a NUL-terminated, zero-padded byte array (maximum usable length 31 bytes). The register is non-volatile and is applied when R_NET_CONFIG is written with the APPLY command.

R_NET_PASSWORD (U8 Array) – Wi-Fi Password

Address 021, length 64 bytes. Stores the Wi-Fi station password as a NUL-terminated, zero-padded byte array (maximum usable length 63 bytes). The register is non-volatile.

Note

For security reasons, this register should be write-only, but the Harp protocol only supports read-only or read/write (full) access types, with no write-only option. The current workaround is to declare the register with read/write access, while the Device returns zeroes when it is read.

Warning

The Wi-Fi password is stored in non-volatile memory, which may be readable by an attacker with physical access to the Device.

R_NET_ENDPOINT (U8 Array) – TCP Endpoint

Address 022, length 18 bytes. The first 16 bytes contain an IPv6 address, or an IPv4 address encoded as an IPv4-mapped IPv6 address (e.g., 192.0.2.10 is encoded as ::ffff:192.0.2.10). The final two bytes contain the TCP port as an unsigned little-endian value. The register is non-volatile.

R_NET_CONFIG (U8) – Network Configuration

Address 023, length 1 byte. Controls Wi-Fi and TCP operation and reports the current network status. It includes enable bits for Wi-Fi and TCP, a read-only WIFI_ABLE capability bit, a 3-bit NET_STATUS group enumerating the available connection states, and the APPLY/CLEAR action bits.

Copilot AI balanced review requested due to automatic review settings October 8, 2026 10:35
@CLAassistant

CLAassistant commented Oct 8, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Password redaction, group-mask encoding, and reply-before-disconnect requirements need correction before approval.

3 open findings
What changed in this PR

Extends Harp’s core register specification to support Wi-Fi and outbound TCP transport for network-capable devices.

Changes:

  • Adds SSID, password, endpoint, and network configuration registers.
  • Defines connection status and configuration commands.
  • Advances the schema protocol version to 1.14.
File Description
schema/​core.yml Adds network register definitions and masks; updates the protocol version.
Device.md Documents network register layouts, behavior, and version history.

🧠 Review effort: Balanced


Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

Comment thread Device.md
Comment on lines +641 to +642
register is non-volatile. For security reasons, the Device MUST return zeroes when
this register is read.
Comment thread Device.md
Comment on lines +694 to +696
This register controls Wi-Fi and TCP operation and reports network status.
The Device MUST ignore status bits supplied by the Controller. The `APPLY`
and `CLEAR` commands are actions and MUST NOT be set together.
Comment thread schema/core.yml
Comment on lines +188 to +200
Apply: {value: 0x40, description: The device will apply the current network configuration.}
Clear: {value: 0x80, description: The device will clear the current network configuration.}
NetworkStatus:
description: Specifies the current network status.
values:
Connected: {value: 0, description: The network is connected.}
Reserved: {value: 0x08, description: Reserved for future use.}
TcpHostUnreachable: {value: 0x10, description: The TCP host could not be reached.}
IpUnavailable: {value: 0x18, description: A valid IP address could not be received.}
WiFiNetworkUnavailable: {value: 0x20, description: The device could not connect to the Wi-Fi network.}
WiFiUnavailable: {value: 0x28, description: Wi-Fi could not be enabled on the device.}
InvalidConfiguration: {value: 0x30, description: The network configuration is invalid or malformed.}
UnknownError: {value: 0x38, description: An unknown network error occurred.}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants