# KiloCenter

Current installation limits: the examples are for isolated evaluation with test data. Published
credentials, signing-key defaults and network exposure need correction before customer use. A
password change alone is insufficient. Read GitBook/05-Security/02-installation-safety.md. Certificate
renewal must preserve data volumes and the existing CA; use GitBook/05-Security/03-certificate-renewal.md.


> KiloCenter is an open-source MIOTY LPWAN network server for managing base stations, endpoints, and IoT message traffic.

Source: https://github.com/Kiloiot/kilo-service-center
License: AGPL-3.0-or-later
Documentation: https://docs.kiloiot.io/kilo-mioty-service-center

## What is this

KiloCenter is the service-center side of the MIOTY stack. MIOTY is a Low Power Wide Area Network (LPWAN) protocol designed for interference resilience, long-range communication, and large endpoint fleets. KiloCenter implements the BSSCI (Base Station - Service Center Interface) and SCACI (Service Center - Application Center Interface) protocols, providing base station management, endpoint registration, uplink/downlink message processing, and application integrations via gRPC and MQTT.

This is a MIOTY-native implementation built from scratch, not a fork or adaptation of another network server.

## Live Demo

https://servicecenter.kiloiot.io/
Username: demo@kiloiot.io
Password: demo1234

## Architecture

Four microservices plus infrastructure:

- KC-Core (port 50051 gRPC, 5000 BSSCI/TLS, 5001 SCACI/TLS, 8086 health) — protocol engines, message processing
- KC-Gateway (port 9090 gRPC-web, 8087 health) — external API ingress, auth proxy
- KC-Identity (port 50052 gRPC, 8088 health) — users, organizations, API keys
- KC-Web (port 80) — React web management console
- PostgreSQL 18+ — primary data store
- Redis 7+ — caching and sessions
- Mosquitto 2.0+ — MQTT broker (optional)

Data flow: Endpoints transmit over radio -> Base stations forward to KC-Core via BSSCI (TCP+TLS) -> KC-Core persists to PostgreSQL -> KC-Gateway exposes gRPC-web API -> KC-Web displays to operators. External systems consume via gRPC or MQTT.

## Technology Stack

- Backend: Go 1.24.4
- Frontend: React 19.1, MUI 7, TypeScript 5.8, Vite
- Database: PostgreSQL with monthly partitioned message tables
- Protocols: BSSCI v1.0.0 (TLS 1.2+), SCACI v1.0.0 (TLS 1.3+)
- API: gRPC + gRPC-web with 117 RPCs
- Infrastructure: Docker Compose, Helm chart for Kubernetes

## Deployment

Three installation paths:

1. Docker Compose: `cp .env.example .env && docker compose up --build -d` — certificates auto-generated
2. Kubernetes: Helm chart at `helm/kilocenter/` — requires external PostgreSQL and Redis
3. Linux Host: build from source with Go and Bun

Default admin account (created on first startup): admin@kilocenter.local / admin123! -- change the password right after the first sign-in. Self-registered accounts start without roles until an administrator grants them (roles: Admin, Tenant Manager, Base Station Manager, Endpoint Manager; see GitBook/05-Security/04-users-and-roles.md).

## API

gRPC-web API exposed through KC-Gateway on port 9090. Proto definitions in `KC-Core/api/proto/`. 117 RPCs covering: endpoints, base stations, messages (with streaming), downlinks, events, alerts, certificates, API keys, blueprints (with per-endpoint pinned snapshots and per-tenant snapshot-only decoding), analytics, organizations, users, SCACI monitoring, system health.

Streaming RPCs: StreamMessages, StreamBaseStationMessages, StreamEvents, StreamBaseStationEvents, StreamEndPointEvents.

## MQTT

Disabled by default. Topic format: `{prefix}/{org_uuid}/device/{ep_eui_hex}/{channel}/{type}`. Channels: event/up (uplinks, with the dlOpen/responseExp/dlAck window flags), event/attach, event/detach, event/downlink_queued (queId of an accepted command, ref echoed), event/downlink_rejected (stable code and message, ref echoed), event/downlink_result (sent/expired/invalid, then acknowledged once when the endpoint confirms a sent downlink; ref of the command on every result; bsEui/txTime/packetCnt when sent), command/down (downlink commands: base64 data of at most 200 bytes, empty for a pure acknowledgement, or counter-dependent entries; optional confirmed, prio, format, responsePrio, dlWindReq, expOnly, dlRxStatQry, ref).

## Key Directories

- KC-Core/ — service center engine, BSSCI/SCACI protocol, gRPC server
- KC-Gateway/ — external gRPC-web ingress
- KC-Identity/ — authentication and user management
- KC-Web/ — React web management console
- KC-DB/ — PostgreSQL persistence, migrations, MIOTY type definitions
- KC-MQTT/ — MQTT integration
- helm/kilocenter/ — Kubernetes Helm chart
- config/ — runtime configuration files
- GitBook/ — user documentation

## Further Reading

- [Architecture and Components](GitBook/02-GettingStarted/01-architecture-and-components.md)
- [Docker Compose Installation](GitBook/02-GettingStarted/03-installation-docker-compose.md)
- [Kubernetes Installation](GitBook/02-GettingStarted/07-installation-kubernetes.md)
- [gRPC API Overview](GitBook/04-Integrations/01-grpc-first-steps.md)
- [MQTT Integration](GitBook/04-Integrations/03-mqtt-first-steps.md)
- [Security](GitBook/05-Security/01-security-and-tenant-isolation-basics.md)
- [Helm Chart README](helm/kilocenter/README.md)