NPC - Nano Protocol for Communication

A lightweight binary protocol designed for IoT, sensors, and real-time messaging.

Why NPC?

Aspect	HTTP/1.1	NPC
Header size	~200-800 bytes	8 bytes fixed
Format	Text (ASCII parsing)	Binary (direct read)
Overhead	High (verbose headers)	Minimal
Patterns	Request/Response only	Request/Response + Push + Pub/Sub
Learning curve	Complex spec	Simple, fits on one page

Protocol Overview

NPC uses a fixed 8-byte header followed by an optional payload:

 0      1      2      3      4      5      6      7
+------+------+------+------+------+------+------+------+
| VER  | TYPE | FLAGS|STATUS|    SEQ ID   |     LEN     |
+------+------+------+------+------+------+------+------+

Message Types: REQUEST, RESPONSE, PUSH, PING, PONG, SUBSCRIBE, UNSUBSCRIBE

Status Codes: OK, ERROR, NOT_FOUND, BUSY, UNAUTHORIZED, FORBIDDEN, TIMEOUT, BAD_REQUEST

See RFC.md for the complete specification.

Implementations

Language	Location	Status
Go	go/	Reference implementation
Python	python/	Complete
Rust	rust/	Complete
TypeScript	typescript/	Complete

All implementations are interoperable and produce identical wire formats.

Quick Start

Go

cd go

# Run the dashboard (server)
go run ./examples/dashboard

# In another terminal, run a sensor (client)
go run ./examples/sensor

Python

cd python

# Run the dashboard
python examples/dashboard.py

# In another terminal, run a sensor
python examples/sensor.py

TypeScript

cd typescript
npm install

# Run the dashboard
npx ts-node examples/dashboard.ts

# In another terminal, run a sensor
npx ts-node examples/sensor.ts

Rust

cd rust

# Run the dashboard
cargo run --example dashboard

# In another terminal, run a sensor
cargo run --example sensor

Cross-Language Interoperability

Mix and match! Start a Go server and connect Python, Rust, and TypeScript clients:

# Terminal 1: Go dashboard
cd go && go run ./examples/dashboard

# Terminal 2: Python sensor
cd python && python examples/sensor.py --id sensor-py

# Terminal 3: TypeScript sensor
cd typescript && npx ts-node examples/sensor.ts localhost 9000 sensor-ts

# Terminal 4: Rust sensor
cd rust && cargo run --example sensor localhost:9000 sensor-rust

All sensors will appear on the Go dashboard, proving protocol compatibility.

Usage Examples

Go Client

import "npc/client"

c, _ := client.Connect("localhost:9000")
defer c.Close()

// Ping
c.Ping()

// Subscribe to topic
c.Subscribe(1) // topic ID 1

// Handle incoming pushes
c.SetPushHandler(func(msg *protocol.Message) {
    fmt.Printf("Received: %s\n", msg.GetData())
})

// Push data
c.Push(1, []byte(`{"temp": 23.5}`))

Python Client

from npc import Client

client = Client()
client.connect("localhost", 9000)

# Ping
rtt = client.ping()

# Subscribe
client.subscribe(topic_id=1)

# Handle pushes
client.set_push_handler(lambda msg: print(f"Received: {msg.get_data()}"))

# Push data
client.push(topic_id=1, data=b'{"temp": 23.5}')

TypeScript Client

import { Client } from 'npc';

const client = new Client();
await client.connect(9000, 'localhost');

// Ping
const rtt = await client.ping();

// Subscribe
await client.subscribe(1);

// Handle pushes
client.setPushHandler((msg) => {
  console.log('Received:', msg.getData().toString());
});

// Push data
await client.push(1, '{"temp": 23.5}');

Testing

# Go
cd go && go test ./...

# Python
cd python && python -m pytest

# Rust
cd rust && cargo test

# TypeScript
cd typescript && npm test

Documentation

• RFC.md - Complete protocol specification
• TUTORIAL.md - Step-by-step guide to understanding and implementing the protocol

Use Cases

1. IoT Sensor Networks - Lightweight data transmission from constrained devices
2. Real-time Telemetry - High-frequency updates with minimal overhead
3. Pub/Sub Messaging - Topic-based message routing
4. Command & Control - Request/response patterns for device management
5. Health Monitoring - Built-in PING/PONG for connection monitoring

License

MIT