goznp

README

goznp

Go library for controlling Zigbee networks via Texas Instruments Z-Stack (ZNP) adapters.

Features

• Device control — on/off, brightness, color temperature, hue/saturation
• Device discovery — automatic interview of endpoints, clusters, and attributes
• Sensor reading — temperature, humidity, pressure, power, battery, occupancy
• Groups and scenes — control multiple devices with a single command
• Network management — form/join networks, permit joining, topology mapping
• Network diagnostics — LQI/RSSI neighbor tables, route discovery
• OTA firmware updates — upgrade device firmware over the air
• Quirks system — automatic workarounds for non-compliant devices
• Device naming — persistent friendly names stored on the coordinator
• Backup/restore — full coordinator NVRAM backup and restore
• REST API daemon (goznpd) — HTTP interface for device control
• CLI tool (goznp) — command-line interface for all operations

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/marstid/goznp/pkg/adapter"
)

func main() {
    a := adapter.New(adapter.WithSerialPath("/dev/ttyUSB0"))

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    if err := a.Open(ctx); err != nil {
        log.Fatal(err)
    }
    defer a.Close()

    devices, err := a.GetDevices(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, dev := range devices {
        fmt.Printf("Device: %s %s (0x%04X)\n", dev.Manufacturer, dev.Model, dev.NwkAddr)
    }
}

Installation

Library

go get github.com/marstid/goznp

CLI tool

go install github.com/marstid/goznp/cmd/goznp@latest

Daemon

go install github.com/marstid/goznp/cmd/goznpd@latest

Or build from source:

make build       # CLI only
make build-all   # CLI + daemon

Hardware

Supported coordinators running Koenkk Z-Stack 3.x.0 firmware:

Chip	Boards
CC2652R / CC2652RB	SONOFF ZBDongle-E, Electrolama zig-a-zig-ah!
CC2652P	SONOFF ZBDongle-P, Tube's CC2652P2
CC1352P	LAUNCHXL-CC1352P

Connect the coordinator via USB. The serial port will appear as:

• Linux: /dev/ttyUSB0 or /dev/ttyACM0
• macOS: /dev/tty.usbserial-110
• Windows: COM3

Use goznp scan to auto-detect connected adapters.

CLI

The goznp CLI provides commands for all adapter operations:

# Scan for adapters
goznp scan

# Connect and show adapter info
goznp connect --port /dev/ttyUSB0

# List paired devices
goznp device list --port /dev/ttyUSB0

# Control a device
goznp device on --addr 0x1234 --endpoint 1
goznp device off --addr 0x1234 --endpoint 1

# Set device brightness
goznp device brightness --addr 0x1234 --endpoint 1 --level 128

# Network management
goznp network info
goznp network form --channel 15
goznp network permit-join --seconds 60
goznp network tree

Set GOZNP_PORT to avoid passing --port every time:

export GOZNP_PORT=/dev/ttyUSB0

See docs/CLI.md for the full command reference.

Daemon

goznpd runs as a background service exposing a REST API:

GOZNP_PORT=/dev/ttyUSB0 goznpd

# List devices
curl http://localhost:8080/api/v1/devices

# Control by slug
curl -X POST http://localhost:8080/api/v1/devices/living-room-light/on

# Read sensor data
curl http://localhost:8080/api/v1/devices/outdoor-plug/sensor

See docs/DAEMON.md for the full API reference, Docker setup, and systemd configuration.

Documentation

Resource	Description
Getting Started	Hardware setup, first pairing, first control
Examples	Runnable code samples (basics, control, advanced)
API Reference	Go package documentation
CLI Reference	Full CLI command reference
Daemon Reference	REST API, Docker, systemd
Architecture	Internal design and development guide
Contributing	Coding standards and hardware testing

Architecture

goznp is a layered library with minimal dependencies (2 direct: cobra, serial):

Application
    |
    v
pkg/adapter    High-level API (device control, network management)
    |
    v
pkg/znp        Z-Stack Network Processor protocol (ZDO, AF, SYS, UTIL)
    |
    v
pkg/unpi       Unified Network Processor Interface (frame encoding/decoding)
    |
    v
pkg/serial     Serial port communication

Supporting packages:

• pkg/zcl — Zigbee Cluster Library (frame building, data types, cluster constants)
• pkg/ota — OTA firmware update server and image parsing
• pkg/backup — Coordinator NVRAM backup format

License

MIT

Documentation

Overview

Package goznp provides a Go library for controlling Zigbee networks via Texas Instruments Z-Stack Network Processor (ZNP) adapters.

The library is organized into layered packages:

• github.com/marstid/goznp/pkg/adapter — High-level API for device control, network management, and diagnostics. This is the main entry point for most users.
• github.com/marstid/goznp/pkg/znp — Z-Stack Network Processor protocol layer (ZDO, AF, SYS, UTIL commands).
• github.com/marstid/goznp/pkg/zcl — Zigbee Cluster Library types, frame building/parsing, and cluster constants.
• github.com/marstid/goznp/pkg/unpi — Unified Network Processor Interface for frame encoding and decoding.
• github.com/marstid/goznp/pkg/ota — OTA firmware update server and image parsing.
• github.com/marstid/goznp/pkg/backup — Coordinator NVRAM backup format.

Getting Started

Most users should start with the adapter package:

a := adapter.New(adapter.WithSerialPath("/dev/ttyUSB0"))
if err := a.Open(ctx); err != nil {
    log.Fatal(err)
}
defer a.Close()

See the examples directory for runnable code samples covering device discovery, control, sensors, and advanced integrations.

Hardware

This library supports Texas Instruments CC2652R/RB, CC2652P, and CC1352P coordinators running Koenkk Z-Stack 3.x.0 firmware.