az-device-contract-codegen 2026.5.18

Generate deterministic Modbus C, Markdown, and Tokio client artifacts from typed device contract definitions.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# az-device-contract-codegen

Generate deterministic Modbus contract artifacts from typed service definitions.

- Crate: `az-device-contract-codegen`
- Local path: `creates/az-device-contract-codegen`
- Install: `cargo add az-device-contract-codegen`

The crate plans a Modbus address layout, then emits a stable artifact bundle for:

- C headers and sources for RTU/TCP handlers
- Markdown protocol documents
- Rust client code built around `tokio-modbus`

## Minimal usage

```rust
use az_device_contract_codegen::{
    generate_bundle, ApiKind, ContractMethod, ContractRenderRequest, ContractService,
    ContractTypedItem, ReadReturnKind, TransportKind, ValueType,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request = ContractRenderRequest {
        transports: vec![TransportKind::Rtu, TransportKind::Tcp],
        services: vec![ContractService {
            api_kind: ApiKind::RuntimeRead,
            interface_name: "DeviceReadApi".into(),
            interface_summary: Some("Runtime reads".into()),
            methods: vec![ContractMethod {
                summary: Some("Read signal lights".into()),
                method_name: "getSignalLights".into(),
                read_return_kind: Some(ReadReturnKind::Dto),
                read_return_type_name: Some("SignalLights".into()),
                read_area: None,
                write_area: None,
                read_fields: vec![
                    ContractTypedItem {
                        name: "ch1".into(),
                        summary: None,
                        value_type: ValueType::Boolean,
                    },
                    ContractTypedItem {
                        name: "ch2".into(),
                        summary: None,
                        value_type: ValueType::Boolean,
                    },
                ],
                parameters: vec![],
            }],
        }],
    };

    let bundle = generate_bundle(&request)?;

    for artifact in &bundle.artifacts {
        println!("{}", artifact.relative_path.display());
    }
    Ok(())
}
```

Typical output paths:

- `Core/Inc/generated/modbus/*.h`
- `Core/Src/generated/modbus/**/*.c`
- `Docs/generated/modbus/protocols/*.md`
- `Docs/generated/modbus/rust/*.rs`

## Default mapping rules

- `STATIC_READ` defaults to input registers (`0x04`)
- `RUNTIME_READ`
  - all-boolean DTO/scalar reads default to discrete inputs (`0x02`)
  - everything else defaults to input registers (`0x04`)
- `WRITE`
  - all-boolean parameters default to coils (`0x05` / `0x0F`)
  - everything else defaults to holding registers (`0x06` / `0x10`)

`readArea` and `writeArea` can override those defaults explicitly.

## Notes

- The crate itself does not write files; it returns `GeneratedArtifact` values.
- Generated Rust clients assume the consumer compiles them with `tokio-modbus` and `serialport`.
- Generated filenames and helper symbols currently use the existing `okm_*` naming line used by this repository.