19 Input Specification

This document defines the input specifications for OSynaptic-FX at different calling levels, focusing on answering: who provides transmission rules and which fields are required.

1. Terminology and Layering

Business Input Layer: Input to osfx_glue_encode_sensor_auto(...) calls.
Wire Protocol Input Layer: Binary frames received over the network passed to osfx_glue_process_packet(...).
Low-level Frame Construction Layer: Input directly calling osfx_packet_encode_full/ex(...) (advanced usage).

2. Business Input Layer (OpenSynaptic Standard Calibration)

Standard transmission API calibration (reference SEND_API_INDEX.md / SEND_API_REFERENCE.md):

transmit(sensors=[ [sensor_id, status, value, unit], ... ])

On the OSynaptic-FX side, this is equivalent to osfx_glue_encode_sensor_auto(...) (single sensor) or multi-sensor wrapper.

2.1 Required Fields (User/Business Side Provides)

Field	Type	Required	Example	Notes
`tid`	`uint8_t`	Yes	`1`	Transaction/channel identifier
`timestamp_raw`	`uint64_t`	Yes	`1710001000`	Recommended to be monotonically increasing
`sensor_id`	`string`	Yes	`TEMP`	Avoid containing `\|`
`input_value`	`double`	Yes	`23.5`	Raw sensor value
`input_unit`	`string`	Yes	`cel` / `kPa`	See `docs/18-standardized-units.md`

2.2 System Auto-Generated Fields (User Should Not Provide)

Field	Source
`cmd`	Auto-selected FULL/DIFF/HEART by `fusion_state`
`route_count`	Fixed to `1`
`source_aid`	`osfx_glue_ctx.local_aid`
`body`	Generated by standardization+Base62 encoding
`crc8` / `crc16`	Auto-calculated internally

2.3 Transmission Rules

Perform unit standardization first.
Encode sensor_id|unit|b62_value.
State machine determines cmd.
Finally frame and calculate CRC.

3. Wire Protocol Input Layer (Reception and Dispatch)

Interface: osfx_glue_process_packet(...)

Caller must provide complete binary frame (already in OpenSynaptic wire format):

Field	Required	Notes
`cmd`	Yes	Byte 0
`route_count`	Yes	Byte 1, currently should be `1`
`source_aid`	Yes	u32, big-endian
`tid`	Yes	u8
`timestamp_raw`	Yes	u48, big-endian
`body`	Yes	Business payload
`crc8`	Yes	Body CRC
`crc16`	Yes	Frame CRC

If fields are missing/CRC error/sequence anomaly, dispatch layer must reject and provide error or NACK.

4. Control Frame Input Specification (Common)

4.1 `ID_REQUEST`

Minimal structure: [cmd:1][seq:2]
Required: cmd=1, seq
Optional business extension: C99 core currently does not require additional JSON metadata

4.2 `TIME_REQUEST`

Minimal structure: [cmd:1][seq:2]

4.3 `SECURE_DICT_READY`

Structure: [cmd:1][aid:4][timestamp_raw:8]

4.4 `SECURE_CHANNEL_ACK`

Structure: [cmd:1][aid:4]

5. Low-level Frame Construction Layer (Advanced)

Interface: osfx_packet_encode_full(...) / osfx_packet_encode_ex(...)

In this mode, caller must provide cmd/source_aid/tid/timestamp/body, applicable for:

Gateway protocol bridging
Test tools
Special control plane frame construction

Not recommended for normal business code to use directly.

6. Input Validation Recommendations (Before Transmission)

sensor_id is non-empty and length within business constraints.
input_unit is in whitelist (see docs/18-standardized-units.md).
timestamp_raw never rolls back (at least monotonic per device).
Buffer capacity is sufficient (avoid truncation).
Errors must be rejected immediately, never send with errors.

7. Typical Errors and Handling

OSFX_GLUE_ERR_ARG: Missing/invalid field.
OSFX_GLUE_ERR_CODEC: Standardization or encoding failure.
OSFX_GLUE_ERR_RUNTIME: Runtime dependency unavailable (session/routing/plugin).

8. Reference Documents

Wire format specification: docs/17-glue-step-by-step.md
Units specification: docs/18-standardized-units.md
Detailed examples: docs/16-examples-cookbook.md

8.1 Basic Config and Compile-Time Effective

OSynaptic-FX supports driving compile-time switches using basic configuration files:

Configuration source: OSynaptic-FX/Config.json
Generated header: OSynaptic-FX/include/osfx_build_config.h
Build configuration header: include/osfx_build_config.h (committed in repository)

Currently effective compile-time switches (examples):

OSFX_CFG_PLUGIN_TRANSPORT
OSFX_CFG_PLUGIN_TEST_PLUGIN
OSFX_CFG_PLUGIN_PORT_FORWARDER
OSFX_CFG_AUTOLOAD_TRANSPORT
OSFX_CFG_AUTOLOAD_TEST_PLUGIN
OSFX_CFG_AUTOLOAD_PORT_FORWARDER

payload_switches will generate corresponding macros (OSFX_CFG_PAYLOAD_*), and have been integrated into multi-sensor template encoding path (osfx_core_encode_multi_sensor_packet_auto(...)):

DeviceId / DeviceStatus / Timestamp / SubTemplateId
SensorId / SensorStatus / PhysicalAttribute / NormalizedValue
GeohashId / SupplementaryMessage / ResourceUrl

9. Complete Example: 10 Sensor Transmission (Including All Fields)

This example provides a complete field view of "business input layer + wire protocol layer" for integration reference.

9.1 Business Input Layer (User Provides)

Call: osfx_glue_encode_multi_sensor_packet_auto(...) (or equivalent upper-layer wrapper)

Below is the OpenSynaptic standard transmission calibration (4-tuple).

tid = 2
timestamp_raw = 1710001234
node_id = NODE_A
node_state = ONLINE

sensors[10] = {
  [TEMP1, OK, 23.5, cel],
  [TEMP2, OK, 24.1, cel],
  [PRESS1, OK, 101.3, kPa],
  [PRESS2, OK, 99.8, kPa],
  [HUM1, OK, 55.0, %],
  [HUM2, OK, 57.2, %],
  [FLOW1, OK, 12.7, L/min],
  [FLOW2, OK, 13.1, L/min],
  [VIB1, OK, 0.82, g],
  [VIB2, OK, 0.79, g]
}

Corresponding C compilable form (standard fields) is as follows:

osfx_core_sensor_input sensors[10] = {
    {"TEMP1", "OK", 23.5, "cel", "", "", ""},
    {"TEMP2", "OK", 24.1, "cel", "", "", ""},
    {"PRESS1", "OK", 101.3, "kPa", "", "", ""},
    {"PRESS2", "OK", 99.8, "kPa", "", "", ""},
    {"HUM1", "OK", 55.0, "%", "", "", ""},
    {"HUM2", "OK", 57.2, "%", "", "", ""},
    {"FLOW1", "OK", 12.7, "L/min", "", "", ""},
    {"FLOW2", "OK", 13.1, "L/min", "", "", ""},
    {"VIB1", "OK", 0.82, "g", "", "", ""},
    {"VIB2", "OK", 0.79, "g", "", "", ""}
};

Extended mode (non-standard calibration) can use:

geohash_id
supplementary_message
resource_url

But this mode requires consistent parser support on both sides, not recommended for "strict OpenSynaptic compatible" links.

Field alignment relationship (extended mode):

Pseudo-syntax id/state/value/unit/geohash/msg/url
Corresponds to C fields sensor_id/sensor_state/value/unit/geohash_id/supplementary_message/resource_url

9.2 System Auto-Generated/Determined Fields

cmd: Auto-determined by fusion_state (first frame typically DATA_FULL=63).
route_count: Fixed to 1.
source_aid: From osfx_glue_ctx.local_aid (e.g., 500).
Standardized output unit and b62_value: Auto-generated by standardization+Base62.
crc8, crc16: Auto-calculated and written.

9.3 Multi-Sensor Body (Template Syntax)

Strict compatible syntax (recommended):

node_id.node_state.ts|sensor_id>sensor_state.sensor_unit:sensor_value|...

Extended syntax (extended mode only):

node_id.node_state.ts|sensor_id>sensor_state.sensor_unit:sensor_value[#geohash][!msg][@url]|...

10 sensor example (strict compatible, symbolic display):

NODE_A.ONLINE.1710001234|
TEMP1>OK.K:<b62_temp1>|TEMP2>OK.K:<b62_temp2>|
PRESS1>OK.Pa:<b62_press1>|PRESS2>OK.Pa:<b62_press2>|
HUM1>OK.%:<b62_hum1>|HUM2>OK.%:<b62_hum2>|
FLOW1>OK.<std_unit_flow>:<b62_flow1>|FLOW2>OK.<std_unit_flow>:<b62_flow2>|
VIB1>OK.<std_unit_vib>:<b62_vib1>|VIB2>OK.<std_unit_vib>:<b62_vib2>|

Notes:

Temperature cel standardizes to unit K.
Pressure kPa standardizes to unit Pa.
Other units standardized per library rules (see docs/18-standardized-units.md).
In extended mode, field order is fixed: #geohash -> !supplementary_message -> @resource_url.

9.4 Wire Protocol Layer Complete Fields (Final Frame)

Field	Value Example	Provided By
`cmd`	`63` (`DATA_FULL`)	system
`route_count`	`1`	system
`source_aid`	`500`	system (`glue.local_aid`)
`tid`	`2`	user
`timestamp_raw`	`1710001234`	user
`body`	Complete string after template encoding	mixed (user + system)
`crc8`	`<auto_crc8>`	system
`crc16`	`<auto_crc16>`	system

Note: <auto_crc8> and <auto_crc16> should not be filled by users, must be auto-calculated by encoder based on actual body.

9.5 Transmission Rules Implementation Conclusion

User responsible for "business fields" (tid/timestamp/node/sensors).
System responsible for "protocol fields" (cmd/aid/crc/wire format assembly).
Users should not manually define cmd (auto path).

9.6 Real Measurement Example (10 sensors, compiled per current `Config.json`)

The following example is from current build measurement output (cmd=63, first frame FULL):

cmd=63
packet_len=303
source_aid=500
tid=2
timestamp_raw=1710001234
body_len=287
body=NODE_A.ONLINE.1710001234|TEMP1>OK.NA:crIM!msg_temp1|TEMP2>OK.NA:cthy!msg_temp2|PRESS1>OK.NA:16yrzG!msg_press1|PRESS2>OK.NA:15xvoc!msg_press2|HUM1>OK.NA:2j4Y!msg_hum1|HUM2>OK.NA:2oNO!msg_hum2|FLOW1>OK.NA:x2o!msg_flow1|FLOW2>OK.NA:y4U!msg_flow2|VIB1>OK.NA:8!msg_vib1|VIB2>OK.NA:7!msg_vib2|
packet_hex=3F01000001F402000065EC8C524E4F44455F412E4F4E4C494E452E313731303030313233347C54454D50313E4F4B2E4E413A6372494D216D73675F74656D70317C54454D50323E4F4B2E4E413A63746879216D73675F74656D70327C5052455353313E4F4B2E4E413A313679727A47216D73675F7072657373317C5052455353323E4F4B2E4E413A313578766F63216D73675F7072657373327C48554D313E4F4B2E4E413A326A3459216D73675F68756D317C48554D323E4F4B2E4E413A326F4E4F216D73675F68756D327C464C4F57313E4F4B2E4E413A78326F216D73675F666C6F77317C464C4F57323E4F4B2E4E413A793455216D73675F666C6F77327C564942313E4F4B2E4E413A38216D73675F766962317C564942323E4F4B2E4E413A37216D73675F766962327CCA12E3

Field interpretation (per current payload_switches):

PhysicalAttribute=false => sensor_unit output as NA
SupplementaryMessage=true => !msg_xxx appears after each sensor value
GeohashId=false => #geohash does not appear
ResourceUrl=false => @url does not appear

To see geohash/url in body, set corresponding switches to true and recompile.

1. Terminology and Layering​

2. Business Input Layer (OpenSynaptic Standard Calibration)​

2.1 Required Fields (User/Business Side Provides)​

2.2 System Auto-Generated Fields (User Should Not Provide)​

2.3 Transmission Rules​

3. Wire Protocol Input Layer (Reception and Dispatch)​

4. Control Frame Input Specification (Common)​

4.1 ID_REQUEST​

4.2 TIME_REQUEST​

4.3 SECURE_DICT_READY​

4.4 SECURE_CHANNEL_ACK​

5. Low-level Frame Construction Layer (Advanced)​

6. Input Validation Recommendations (Before Transmission)​

7. Typical Errors and Handling​

8. Reference Documents​

8.1 Basic Config and Compile-Time Effective​

9. Complete Example: 10 Sensor Transmission (Including All Fields)​

9.1 Business Input Layer (User Provides)​

9.2 System Auto-Generated/Determined Fields​

9.3 Multi-Sensor Body (Template Syntax)​

9.4 Wire Protocol Layer Complete Fields (Final Frame)​

9.5 Transmission Rules Implementation Conclusion​

9.6 Real Measurement Example (10 sensors, compiled per current Config.json)​