README
¶
godlms
Go framework for DLMS/COSEM with SPODES (meter) and SPODUS (ICCE) profile extensions — aligned with Russian metering standards (СТО 34.01-5.1-006 / 013).
Repository: GitLab — trgv/godlms (primary remote)
godlms — фреймворк DLMS/COSEM с профилями СПОДЭС (ПУ) и СПОДУС (ИВКЭ). Архитектура и план: docs/architecture/.
Status
Current release: v0.1.0 · pkg.go.dev
| Area | State |
|---|---|
| A-XDR codec | pkg/axdr/ — implemented |
| BER codec | pkg/ber/ — TLV, BIT STRING, SEQUENCE (Phase 1.1–1.2) |
| ACSE encode/decode | pkg/cosem/acse_codec.go on pkg/ber (Phase 1.2) |
| HDLC / Wrapper / Transport | pkg/hdlc, pkg/wrapper → link.Link; pkg/transport/layer.go + LLC |
| Session | pkg/session/ — classifier + loop (Phase 3.1–3.2) |
| COSEM (ACSE, xDLMS, objects) | ACSE, xDLMS services, IC factory, normative methods, GLO/GBT |
Roadmap and session context: handoff · implementation roadmap · conformance matrix (Phase 7).
Installation
go get gitlab.com/trgv/godlms@v0.1.0
Requires Go 1.23+ (see go.mod).
Quick start
Examples (transport / COSEM demos):
go run ./examples/cli-server # COSEM server (pkg/server, Wrapper :4059)
go run ./examples/client # COSEM client GET register (pkg/client)
go run ./examples/aggregator # ICCE: 2 meters → virtual LDs
See examples/README.md.
Package layout
| Package | Layer | Description |
|---|---|---|
pkg/ber |
Codec | BER for ACSE (Phase 1.1–1.2) |
pkg/llc |
LLC | LSAP wrap/unwrap 0xE6/0xE7 |
pkg/link |
Link/MAC | Link interfaces + registry |
pkg/axdr |
Codec | A-XDR encode/decode (IEC 62056-6-2) |
pkg/hdlc |
Link/MAC | HDLC Frame Type 3 |
pkg/wrapper |
Link/MAC | TCP Wrapper (port 4059) |
pkg/transport |
Transport | Layer over link + LLC (Phase 2.5) |
pkg/session |
Session | PDU classifier + dispatch loop |
pkg/cosem |
Application | ACSE, xDLMS APDU, typed IC, normative methods, security |
pkg/cosem/objects |
Application | DLMS IC schema registry, New(classID, obis), method metadata |
pkg/cosem/objects/spodes |
Application | SPODES meter model builder (NewMeterModel) |
pkg/cosem/objects/spodus |
Application | SPODUS ICCE management objects |
pkg/cosem/objreg |
Application | COSEM object registry (import-cycle safe) |
pkg/common |
— | Shared errors |
pkg/server |
Server | Wrapper-profile COSEM server |
pkg/client |
Client | COSEM client (GET/SET, GBT, SN) |
pkg/gateway/aggregator |
Gateway | ICCE aggregator (Phase 6) |
pkg/gateway/protocol |
Gateway | IEC Annex C prefix relay (Phase 6b) |
pkg/profile/spodes |
Profile | SPODES constraints + IC catalog |
pkg/profile/spodus |
Profile | SPODUS ICCE catalog |
pkg/cosem/conformance |
Application | Yellow Book conformance block (Phase 8.5) |
Documentation
| Document | Description |
|---|---|
| Architecture index | Stack overview, bilingual navigation |
| Plan (EN) · (RU) | Layered architecture v6 |
| Handoff (EN) · (RU) | Current phase / next steps |
| COSEM method catalog · (RU) | Per-class methods: normative vs application |
| Coding style | Google Go Style Guide |
| CI/CD (GitLab) · (RU) | Pipeline, MR workflow (Phase 9) |
Maintaining docs (Phase 0): update this root README.md when pkg/, examples, or install/test flow change; keep in sync with docs/architecture/ (details stay there, not duplicated here).
Versioning
Pre-v1.0.0 releases use semver on v0.x tags; minor bumps may include API changes. Pin v0.1.0 (or later v0.x) in go.mod for reproducible builds. See backlog for optional extensions beyond this release.
Development
go test ./...
go test -run '^Example' ./pkg/... # godoc examples (subset of packages)
go run ./tools/godoccheck # optional: exported symbols missing godoc
golangci-lint run ./... # same as GitLab CI (Phase 9)
SPODES Suite 3 (Kuznyechik+CMAC) is optional — build and test with -tags suite3 (pulls gogost + cmac). Without the tag, suites 0–2 use stdlib AES only; suite 3 returns security.ErrSuiteNotSupported.
go test -tags suite3 ./pkg/cosem/security/... ./pkg/cosem/hls/...
SPODES HLS GOST (CMAC, GOST3411, GOST3410) lives in pkg/cosem/hls and requires the same suite3 build tag.
Style: Google Go Style Guide · gofmt / goimports.
CI/CD: GitLab pipeline on push/MR; release job on v* tags — see ci-cd.md. GitHub Actions is an optional mirror only.
Standards
- DLMS/COSEM Green Book 8.3, IEC 62056
- SPODES — STO 34.01-5.1-006 / GOST R 58940
- SPODUS — STO 34.01-5.1-013 (ICCE information model)
Reference ASN.1: docs/DLMS UA …/GB8.3/ASN.1/COSEMpdu_GB83.asn.
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
aggregator
command
ICCE aggregator demo (СТО 34.01-5.1-013 §6.1): two simulated meters, ICC reads virtual LDs.
|
ICCE aggregator demo (СТО 34.01-5.1-013 §6.1): two simulated meters, ICC reads virtual LDs. |
|
cli-server
command
CLI COSEM meter server (TCP Wrapper).
|
CLI COSEM meter server (TCP Wrapper). |
|
client
command
COSEM client: associate and read an attribute over TCP Wrapper.
|
COSEM client: associate and read an attribute over TCP Wrapper. |
|
gateway
command
Gateway demos: IEC 62056-5-3 Annex C prefix relay (default) or ICCE aggregator walkthrough.
|
Gateway demos: IEC 62056-5-3 Annex C prefix relay (default) or ICCE aggregator walkthrough. |
|
push-listener
command
COSEM client that listens for an unsolicited Data-Notification (push).
|
COSEM client that listens for an unsolicited Data-Notification (push). |
|
push-notify-server
command
Minimal COSEM server that accepts LLS association and sends one Data-Notification.
|
Minimal COSEM server that accepts LLS association and sends one Data-Notification. |
|
server
command
COSEM meter server over TCP Wrapper (IEC 62056-47).
|
COSEM meter server over TCP Wrapper (IEC 62056-47). |
|
udp_client
command
|
|
|
udp_server
command
|
|
|
pkg
|
|
|
axdr
Package axdr implements A-XDR encoding and decoding per IEC 62056-6-2.
|
Package axdr implements A-XDR encoding and decoding per IEC 62056-6-2. |
|
ber
Package ber implements a subset of ASN.1 BER (X.690) for ACSE APDUs.
|
Package ber implements a subset of ASN.1 BER (X.690) for ACSE APDUs. |
|
client
Package client provides a DLMS/COSEM application client over TCP Wrapper or HDLC.
|
Package client provides a DLMS/COSEM application client over TCP Wrapper or HDLC. |
|
common
Package common defines shared application error types used with SPODES/SPODUS profiles.
|
Package common defines shared application error types used with SPODES/SPODUS profiles. |
|
cosem
Package cosem implements the DLMS/COSEM application layer: ACSE, xDLMS APDU, interface classes, access control, and secured APDUs (GLO/DED/General).
|
Package cosem implements the DLMS/COSEM application layer: ACSE, xDLMS APDU, interface classes, access control, and secured APDUs (GLO/DED/General). |
|
cosem/conformance
Package conformance implements the DLMS conformance block (Yellow Book) for negotiate at association and BER bit-string mapping.
|
Package conformance implements the DLMS conformance block (Yellow Book) for negotiate at association and BER bit-string mapping. |
|
cosem/hls
Package hls implements COSEM High-Level Security (HLS) mechanisms: GMAC (suite 0–2) and GOST-based HLS (build tag suite3).
|
Package hls implements COSEM High-Level Security (HLS) mechanisms: GMAC (suite 0–2) and GOST-based HLS (build tag suite3). |
|
cosem/objects
Package objects is the COSEM interface-class factory and schema registry (IEC 62056-6-2 / Blue Book).
|
Package objects is the COSEM interface-class factory and schema registry (IEC 62056-6-2 / Blue Book). |
|
cosem/objects/ic
Package ic documents the COSEM interface-class layout for godlms.
|
Package ic documents the COSEM interface-class layout for godlms. |
|
cosem/objects/spodes
Package spodes builds mandatory SPODES (STO 006) meter COSEM objects, including three Association LN instances (Public, Reader, Configurator).
|
Package spodes builds mandatory SPODES (STO 006) meter COSEM objects, including three Association LN instances (Public, Reader, Configurator). |
|
cosem/objects/spodus
Package spodus builds SPODUS (STO 013) ICCE management objects: device list, status/correction journals, and management model helpers.
|
Package spodus builds SPODUS (STO 013) ICCE management objects: device list, status/correction journals, and management model helpers. |
|
cosem/objreg
Package objreg provides a COSEM object registry without import cycles between pkg/cosem and pkg/cosem/objects.
|
Package objreg provides a COSEM object registry without import cycles between pkg/cosem and pkg/cosem/objects. |
|
cosem/security
Package security implements xDLMS ciphering and signing: GLO/DED layers, General ciphering/signing APDUs, AES suites 0–2, and optional Kuznyechik suite 3 (build tag suite3).
|
Package security implements xDLMS ciphering and signing: GLO/DED layers, General ciphering/signing APDUs, AES suites 0–2, and optional Kuznyechik suite 3 (build tag suite3). |
|
gateway/aggregator
Package aggregator implements the ICCE aggregation gateway (СТО 34.01-5.1-013 §6): southbound polling of meters and northbound virtual logical devices for ICC.
|
Package aggregator implements the ICCE aggregation gateway (СТО 34.01-5.1-013 §6): southbound polling of meters and northbound virtual logical devices for ICC. |
|
gateway/aggregator/icc
Package icc provides a minimal ICC (HES) client over TCP Wrapper with SAP addressing.
|
Package icc provides a minimal ICC (HES) client over TCP Wrapper with SAP addressing. |
|
gateway/aggregator/northbound
Package northbound exposes aggregated meter data as northbound COSEM logical devices.
|
Package northbound exposes aggregated meter data as northbound COSEM logical devices. |
|
gateway/aggregator/proxy
Package proxy mirrors southbound poll results into northbound COSEM attributes.
|
Package proxy mirrors southbound poll results into northbound COSEM attributes. |
|
gateway/aggregator/registry
Package registry holds southbound device configuration and poll schedules for the ICCE aggregator.
|
Package registry holds southbound device configuration and poll schedules for the ICCE aggregator. |
|
gateway/aggregator/scheduler
Package scheduler runs periodic southbound polls and stores results via handlers.
|
Package scheduler runs periodic southbound polls and stores results via handlers. |
|
gateway/aggregator/southbound
Package southbound maintains DLMS client connections to physical meters.
|
Package southbound maintains DLMS client connections to physical meters. |
|
gateway/aggregator/store
Package store caches the latest southbound poll readings keyed by device and attribute.
|
Package store caches the latest southbound poll readings keyed by device and attribute. |
|
gateway/protocol
Package protocol implements IEC 62056-5-3 Annex C / Green Book §10.7 DLMS Gateway Protocol (prefix routing 0xE6/0xE7).
|
Package protocol implements IEC 62056-5-3 Annex C / Green Book §10.7 DLMS Gateway Protocol (prefix routing 0xE6/0xE7). |
|
gateway/protocol/prefix
Package prefix encodes Annex C pre-fixed gateway fields ahead of a COSEM APDU.
|
Package prefix encodes Annex C pre-fixed gateway fields ahead of a COSEM APDU. |
|
hdlc
Package hdlc implements IEC 62056-46 HDLC frame Type 3 over a link.Link MAC.
|
Package hdlc implements IEC 62056-46 HDLC frame Type 3 over a link.Link MAC. |
|
link
Package link defines the link/MAC abstraction and registers HDLC and Wrapper profiles.
|
Package link defines the link/MAC abstraction and registers HDLC and Wrapper profiles. |
|
llc
Package llc implements the LLC sublayer (LSAP 0xE6/0xE7) for COSEM over HDLC.
|
Package llc implements the LLC sublayer (LSAP 0xE6/0xE7) for COSEM over HDLC. |
|
profile
Package profile defines conformance profiles (DLMS baseline, SPODES, SPODUS).
|
Package profile defines conformance profiles (DLMS baseline, SPODES, SPODUS). |
|
profile/spodes
Package spodes defines the SPODES meter profile (STO 34.01-5.1-006 / GOST R 58940): mandatory IC catalog, security suites, and conformance defaults.
|
Package spodes defines the SPODES meter profile (STO 34.01-5.1-006 / GOST R 58940): mandatory IC catalog, security suites, and conformance defaults. |
|
profile/spodus
Package spodus defines the SPODUS ICCE profile (STO 34.01-5.1-013) and northbound management model construction.
|
Package spodus defines the SPODUS ICCE profile (STO 34.01-5.1-013) and northbound management model construction. |
|
server
Package server provides a COSEM server over TCP Wrapper with profile-aware models.
|
Package server provides a COSEM server over TCP Wrapper with profile-aware models. |
|
session
Package session classifies incoming PDUs (ACSE vs xDLMS) and dispatches them through a transport-backed application loop with optional security middleware.
|
Package session classifies incoming PDUs (ACSE vs xDLMS) and dispatches them through a transport-backed application loop with optional security middleware. |
|
transport
Package transport combines link.MAC and LLC framing into a single Read/Write layer.
|
Package transport combines link.MAC and LLC framing into a single Read/Write layer. |
|
wrapper
Package wrapper implements IEC 62056-47 TCP Wrapper (port 4059) as a link.Link profile.
|
Package wrapper implements IEC 62056-47 TCP Wrapper (port 4059) as a link.Link profile. |
|
tools
|
|
|
godoccheck
command
Command godoccheck lists exported Go symbols without documentation.
|
Command godoccheck lists exported Go symbols without documentation. |
|
meterprobe
command
meterprobe tries transport/security combos against a live meter.
|
meterprobe tries transport/security combos against a live meter. |
Click to show internal directories.
Click to hide internal directories.