Station Device Network (SDN)

Protocol Specification & Datasheet
Document Version 1.1
Protocol Version SDN-1.0
Date December 2032
Status Active

1. Overview

The Station Device Network (SDN) protocol is a comprehensive inter-device messaging framework designed for critical space station systems. It provides reliable, structured communication between life support equipment, environmental controls, pressure suits, airlocks, and monitoring systems.

1.1 Key Features

  • Packed binary format for efficient bandwidth utilization
  • Timestamped messages for event sequencing
  • Support for sensor telemetry and control commands
  • Health monitoring and fault management
  • Variable-length payloads for flexible data structures
  • Command-response architecture with status reporting

1.2 Target Applications

  • Environmental Control and Life Support Systems (ECLSS)
  • Airlock sequencing and pressure management
  • Pressure suit monitoring and configuration
  • Emergency response coordination
  • System health monitoring and diagnostics

2. Device Types

Type ID Device Type Description
0 INVALID Invalid/uninitialized device type
1 SUIT Pressure suit with integrated life support systems
2 PANEL Control panel interface for manual operation
3 REMOTE Remote terminal or monitoring station
4 DOOR Standard door with pressure sensors on both sides
5 AIRLOCK_CTRL Airlock controller with dual-door coordination and safety interlocks

3. Message Structure

3.1 Common Header (SDNMsgHeader)

All messages begin with a common 16-byte header:

Offset Size Field Description
0 2 bytes msg_type Message type identifier (see section 4)
2 2 bytes msg_length Total message size including header
4 4 bytes device_id Unique identifier of sending device
8 8 bytes timestamp Message creation time in milliseconds
Note All structures use packed alignment (#pragma pack(1)) to ensure consistent binary layout across platforms. This is critical for network communication.

3.2 Variable-Length Messages

Several message types include flexible array members for variable-length payloads. The actual payload size is determined by:

payload_size = msg_header.msg_length - sizeof(fixed_fields)

4. Message Types

4.1 Heartbeat (Type 1)

Periodic health status message broadcast by all devices. Must be sent regularly to avoid timing out.

Field Type Description
msg_header SDNMsgHeader Standard message header
health uint32_t Health status: 0 = healthy (SDN_HEALTH_GOOD), non-zero = fault bits

Size: 20 bytes

4.2 Sensor Pressure (Type 2)

Atmospheric pressure measurement from environmental sensors. Multiple sensors on a device are disambiguated by measurement_id.

Field Type Description
msg_header SDNMsgHeader Standard message header
measurement_id uint32_t Sensor identifier (see predefined IDs)
pressure_pa float Pressure reading in Pascals

Size: 24 bytes

Predefined Measurement IDs

  • SDN_MEASUREMENT_ID_DOOR_PRESSURE_SIDE_1 = 1
  • SDN_MEASUREMENT_ID_DOOR_PRESSURE_SIDE_2 = 2

4.3 Set Pressure Zone (Type 3)

Command to open pressure valve to specified equalization zone.

Field Type Description
msg_header SDNMsgHeader Standard message header
zone_id uint8_t Target pressure zone identifier

Size: 17 bytes

4.4 Set Open (Type 4)

Generic open/close command for standard doors and hatches.

Field Type Description
msg_header SDNMsgHeader Standard message header
open uint8_t 0=closed, non-zero=open

Size: 17 bytes

4.5 Set Airlock Open (Type 5)

Airlock door control command. Controls which airlock door (if any) is open. Safety interlocks prevent both doors from opening simultaneously.

Field Type Description
msg_header SDNMsgHeader Standard message header
open uint8_t Door state (see SDNAirlockOpen enum)

Size: 17 bytes

Airlock States (SDNAirlockOpen)

Value State Description
0 CLOSED Both doors sealed
1 INTERIOR_OPEN Station-side door open
2 EXTERIOR_OPEN Space-side door open
Safety Critical - Airlock Operation Airlock controllers must enforce interlocks preventing simultaneous opening of both doors. Attempted dual-door open commands must be rejected.

Airlock Command Behavior

Pre-Conditions
  • Command is rejected if any fault bits are active (returns SDN_RESPONSE_CMD_ERROR_1)
  • Message length must be valid (returns SDN_RESPONSE_INVALID_MSG_LEN if too small)

1. SDN_AIRLOCK_CLOSED

Closes both interior and exterior doors. Transitions state based on which door was previously open:

  • From INTERIOR_OPEN: Transitions to CLOSED_PRESSURIZED
  • From EXTERIOR_OPEN: Transitions to CLOSED_DEPRESSURIZED

2. SDN_AIRLOCK_INTERIOR_OPEN (Station-side)

  • From CLOSED_PRESSURIZED: Directly opens interior door
  • From EXTERIOR_OPEN / CLOSED_DEPRESSURIZED / DEPRESSURIZING:
    • Closes exterior door
    • Initiates pressurization sequence
    • Enters PRESSURIZING state (door opens when pressurization completes)
  • Already INTERIOR_OPEN or PRESSURIZING: No action (idempotent)

3. SDN_AIRLOCK_EXTERIOR_OPEN (Space-side)

Critical Safety Check Queries occupancy sensor to verify all occupants have sealed suits:
  • Rejects command if any occupant is unsealed (returns SDN_RESPONSE_CMD_ERROR_2)
  • Rejects if too many occupants present
  • From CLOSED_DEPRESSURIZED: Directly opens exterior door
  • From INTERIOR_OPEN / CLOSED_PRESSURIZED / PRESSURIZING:
    • Closes interior door
    • Initiates depressurization sequence
    • Enters DEPRESSURIZING state (door opens when depressurization completes)
  • Already EXTERIOR_OPEN or DEPRESSURIZING: No action
Key Safety Features
  • Never allows both doors open simultaneously
  • Requires pressure equalization before door transitions
  • Validates suit status before exposing occupants to vacuum
  • Fatal error (exit) on door/pressure control failures

4.6 Sensor Occupancy (Type 6)

Reports personnel presence and suit status. Variable-length message. The measurement_id identifies the sensor/location.

Field Type Description
msg_header SDNMsgHeader Standard message header
measurement_id uint32_t Sensor/location identifier
occupants[] SDNOccupancyInfo[] Array of occupant records (variable length)

Minimum Size: 20 bytes (no occupants)

SDNOccupancyInfo Structure

Field Type Size Description
user_id uint32_t 4 bytes Unique personnel identifier
suit_status uint8_t 1 byte 0=INVALID, 1=SEALED, 2=UNSEALED

4.7 Debug Write Config Int (Type 7)

Runtime configuration parameter update for testing and calibration. By default, configuration is only reloaded by resetting the device.

Field Type Description
msg_header SDNMsgHeader Standard message header
key[32] char[] Configuration key name (null-terminated)
value int32_t New configuration value

Size: 52 bytes

Note
  • This command is intended for testing and debugging. Production systems should use persistent configuration files.
  • While this configuration parameter is represented as an int32_t, it will implicitly be cast as needed if the key corresponds to other types (e.x. bool, uint32_t).

4.8 Clear Faults (Type 8)

Command to reset fault conditions after corrective action.

Field Type Description
msg_header SDNMsgHeader Standard message header
fault_mask uint32_t Bitmask of faults to clear (application-defined)

Size: 20 bytes

4.9 Log (Type 9)

Diagnostic and operational log message. Variable-length message.

Field Type Description
msg_header SDNMsgHeader Standard message header
severity uint8_t 0=CRITICAL, 1=ERROR, 2=WARNING, higher values less severe
message_str[] char[] Log message text (null-terminated, variable length)

Minimum Size: 17 bytes (empty message)

4.10 Set Suit Occupant (Type 10)

Unlocks and configure pressure suit for specific user. Variable-length message.

Field Type Description
msg_header SDNMsgHeader Standard message header
user_id uint32_t User identifier to configure suit for
user_preferences[] uint8_t[] Custom preference data (variable length)

Minimum Size: 20 bytes (no preferences)

4.11 Command Response (Type 11)

Sent in response to a command message to indicate execution status.

Field Type Description
msg_header SDNMsgHeader Standard message header
response_code uint8_t Response status code (see SDNResponseStatus)

Size: 17 bytes

5. Response Status Codes

Commands return status codes indicating success or failure reason:

Code Constant Description
0 SDN_RESPONSE_GOOD Operation completed successfully
1 SDN_RESPONSE_FAILED Operation failed (generic error)
2 SDN_RESPONSE_BUFFER_TOO_SMALL Provided buffer insufficient for response
3 SDN_RESPONSE_INVALID_MSG_LEN Message had invalid length
4 SDN_RESPONSE_CMD_ERROR_1 Command-specific error (e.g., faults active)
5 SDN_RESPONSE_CMD_ERROR_2 Command-specific error (e.g., unsafe conditions)
6 SDN_RESPONSE_CMD_ERROR_3 Command-specific error (e.g., timeout)

6. API Functions

6.1 Device Management

RegisterDevice

bool RegisterDevice(uint32_t device_id, SDNDeviceType device_type)

Description: Registers a device with the SDN network. Must be called during device initialization before any message transmission or reception.

Parameter Type Description
device_id uint32_t Unique identifier for this device (must be unique across the network)
device_type SDNDeviceType Device category: SUIT, PANEL, REMOTE, DOOR, or AIRLOCK_CTRL

Returns:

  • true - Registration successful, device can now send/receive messages
  • false - Registration failed (device_id already in use or invalid device_type)
Critical This function must be called successfully before any other SDN operations. Attempting to use other functions before registration will result in undefined behavior.

6.2 Messaging & Subscription

SubscribeToMessage

bool SubscribeToMessage(uint32_t device_id, SDNMsgType message_type)

Description: Subscribes to receive messages of a specific type from a specific device. Once subscribed, messages of that type from the specified device will be delivered via ReadNextMessage().

Parameter Type Description
device_id uint32_t The device to subscribe to (source device)
message_type SDNMsgType Type of message to receive (HEARTBEAT, SENSOR_PRESSURE, etc.)

Returns:

  • true - Subscription successful
  • false - Subscription failed (invalid device_id or message_type)
Note Multiple subscriptions can be active simultaneously. Call this function once for each device/message-type combination you want to receive.

ReadNextMessage

int ReadNextMessage(void *msg_buffer, size_t buffer_size_bytes)

Description: Blocking call that retrieves the next available message from subscribed sources. Returns when a message is available or an error occurs. The message will always begin with an SDNMsgHeader.

Parameter Type Description
msg_buffer void* Buffer to store the received message
buffer_size_bytes size_t Size of the provided buffer in bytes

Returns:

  • Positive value: Number of bytes read (message size)
  • Negative value: Error code (network error, buffer too small, etc.)
Warning This is a blocking call. The function will not return until a message is received or an error occurs. For non-blocking operation, implement timeout handling or use a separate thread.

6.3 Health Monitoring

BroadcastHeartbeat

bool BroadcastHeartbeat(uint32_t fault_bits)

Description: Broadcasts a heartbeat message to the network indicating device health status. This must be called periodically to prevent the device from being marked as unresponsive or failed.

Parameter Type Description
fault_bits uint32_t Bitmask of current fault conditions (0 = SDN_HEALTH_GOOD, non-zero = fault bits)

Returns:

  • true - Heartbeat broadcast successful
  • false - Broadcast failed (network error)
Recommended Intervals
  • Critical devices (SUIT, AIRLOCK_CTRL): 2 seconds
  • Standard devices (DOOR, PANEL): 5 seconds
  • Monitoring devices (REMOTE): 10 seconds

6.4 Command Execution

ExecuteCmd

bool ExecuteCmd(const SDNMsgHeader *header, uint32_t target_device_id)

Description: Sends a command message to a specific device and waits for acknowledgment of execution. The command will be processed by the target device's message handler.

Parameter Type Description
header const SDNMsgHeader* Pointer to the complete command message (including header and payload)
target_device_id uint32_t Device identifier to execute the command

Returns:

  • true - Command was accepted and acknowledged by target device
  • false - Command was rejected or failed (target unreachable, invalid command, etc.)
Note The header parameter should point to a complete message structure (e.g., SDNSetAirlockOpenMessage, SDNClearFaultsMessage, etc.). The msg_type and msg_length fields must be set correctly.

RequestMessage

SDNResponseStatus RequestMessage(void *msg_buffer, size_t buffer_size_bytes, uint32_t target_device_id, SDNMsgType request_type)

Description: Requests a device to send a specific message type. Used to poll devices for current status or sensor readings. The response is stored in the provided buffer.

Parameter Type Description
msg_buffer void* Buffer to store the response message
buffer_size_bytes size_t Size of the provided buffer
target_device_id uint32_t Device that should respond
request_type SDNMsgType Type of message being requested

Returns:

Status Code Description
SDN_RESPONSE_GOOD Response received successfully, data in msg_buffer
SDN_RESPONSE_FAILED Request failed (device unreachable, timeout, etc.)
SDN_RESPONSE_BUFFER_TOO_SMALL Response message larger than provided buffer
SDN_RESPONSE_INVALID_MSG_LEN Response had invalid message length

SendCmdResponse

void SendCmdResponse(SDNResponseStatus response_code)

Description: Sends a response code after processing a received command. This must be called by command message handlers to acknowledge command processing and indicate success or failure.

Parameter Type Description
response_code SDNResponseStatus Status code indicating success or reason for failure

Common Response Codes:

  • SDN_RESPONSE_GOOD - Command processed successfully
  • SDN_RESPONSE_FAILED - Command failed (generic error)
  • SDN_RESPONSE_INVALID_MSG_LEN - Message length invalid
  • SDN_RESPONSE_CMD_ERROR_1 - Command-specific error
Critical Command handlers MUST call SendCmdResponse() exactly once per received command. Failing to respond will cause the sender to timeout.

6.5 Utility Functions

GetCurrentTimestampMS

sdn_timestamp_t GetCurrentTimestampMS(void)

Description: Returns the current system time in milliseconds since system epoch. Used to populate the timestamp field in message headers.

Returns: Current time in milliseconds (uint64_t)

Note The timestamp is used for message sequencing and timeout detection. All messages should include a valid timestamp obtained from this function.

SleepMS

void SleepMS(unsigned ms)

Description: Blocks execution for the specified duration in milliseconds. Used for implementing periodic tasks like heartbeat transmission.

Parameter Type Description
ms unsigned Duration to sleep in milliseconds