protocol_config_mem_write_handler.c File Reference

Configuration memory write handler implementation. More...

Functions
void	ProtocolConfigMemWriteHandler_initialize (const interface_protocol_config_mem_write_handler_t *interface_protocol_config_mem_write_handler)
	Stores the callback interface. Call once at startup.
void	ProtocolConfigMemWriteHandler_write_space_config_description_info (openlcb_statemachine_info_t *statemachine_info)
	Dispatch CDI (0xFF) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_all (openlcb_statemachine_info_t *statemachine_info)
	Dispatch All (0xFE) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_config_memory (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Config (0xFD) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_acdi_manufacturer (openlcb_statemachine_info_t *statemachine_info)
	Dispatch ACDI-Mfg (0xFC) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_acdi_user (openlcb_statemachine_info_t *statemachine_info)
	Dispatch ACDI-User (0xFB) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_train_function_definition_info (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Train FDI (0xFA) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_train_function_config_memory (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Train Fn Config (0xF9) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_space_firmware (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Firmware (0xEF) write to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_config_description_info (openlcb_statemachine_info_t *statemachine_info)
	Dispatch CDI (0xFF) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_all (openlcb_statemachine_info_t *statemachine_info)
	Dispatch All (0xFE) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_config_memory (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Config (0xFD) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_acdi_manufacturer (openlcb_statemachine_info_t *statemachine_info)
	Dispatch ACDI-Mfg (0xFC) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_acdi_user (openlcb_statemachine_info_t *statemachine_info)
	Dispatch ACDI-User (0xFB) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_train_function_definition_info (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Train FDI (0xFA) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_train_function_config_memory (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Train Fn Config (0xF9) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_under_mask_space_firmware (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Firmware (0xEF) write-under-mask to two-phase handler.
void	ProtocolConfigMemWriteHandler_write_message (openlcb_statemachine_info_t *statemachine_info, uint8_t space, uint8_t return_msg_ok, uint8_t return_msg_fail)
	Processes a generic write message (stub)
void	ProtocolConfigMemWriteHandler_write_reply_ok_message (openlcb_statemachine_info_t *statemachine_info, uint8_t space)
	Processes a write reply OK message (stub)
void	ProtocolConfigMemWriteHandler_write_reply_fail_message (openlcb_statemachine_info_t *statemachine_info, uint8_t space)
	Processes a write reply fail message (stub)
void	ProtocolConfigMemWriteHandler_write_request_config_mem (openlcb_statemachine_info_t *statemachine_info, config_mem_write_request_info_t *config_mem_write_request_info)
	Processes a write request for Configuration Memory space.
void	ProtocolConfigMemWriteHandler_write_request_acdi_user (openlcb_statemachine_info_t *statemachine_info, config_mem_write_request_info_t *config_mem_write_request_info)
	Processes a write request for ACDI User space.
void	ProtocolConfigMemWriteHandler_write_request_train_function_config_memory (openlcb_statemachine_info_t *statemachine_info, config_mem_write_request_info_t *config_mem_write_request_info)
	Processes a write request for Train Function Configuration Memory space (0xF9)

Detailed Description

Configuration memory write handler implementation.

Copyright

Copyright (c) 2024, Jim Kueneman All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Two-phase dispatch for write commands across all standard address spaces. Supports plain write, write-under-mask (read-modify-write), and firmware upgrade writes. Sends Datagram Received OK with reply-pending before performing the actual write operation.

Author

Jim Kueneman

Date

9 Mar 2026

See also

protocol_config_mem_write_handler.h

MemoryConfigurationS.pdf

Function Documentation

ProtocolConfigMemWriteHandler_initialize()

void ProtocolConfigMemWriteHandler_initialize

(

const interface_protocol_config_mem_write_handler_t *

interface_protocol_config_mem_write_handler

)

Stores the callback interface. Call once at startup.

* @param interface_protocol_config_mem_write_handler  Populated table.
* 

Warning

Structure must remain valid for application lifetime.

ProtocolConfigMemWriteHandler_write_space_config_description_info()

void ProtocolConfigMemWriteHandler_write_space_config_description_info

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch CDI (0xFF) write to two-phase handler.

Write to CDI space (0xFF).

ProtocolConfigMemWriteHandler_write_space_all()

void ProtocolConfigMemWriteHandler_write_space_all

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch All (0xFE) write to two-phase handler.

Write to All space (0xFE).

ProtocolConfigMemWriteHandler_write_space_config_memory()

void ProtocolConfigMemWriteHandler_write_space_config_memory

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Config (0xFD) write to two-phase handler.

Write to Config space (0xFD).

ProtocolConfigMemWriteHandler_write_space_acdi_manufacturer()

void ProtocolConfigMemWriteHandler_write_space_acdi_manufacturer

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch ACDI-Mfg (0xFC) write to two-phase handler.

Write to ACDI-Mfg space (0xFC).

ProtocolConfigMemWriteHandler_write_space_acdi_user()

void ProtocolConfigMemWriteHandler_write_space_acdi_user

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch ACDI-User (0xFB) write to two-phase handler.

Write to ACDI-User space (0xFB).

ProtocolConfigMemWriteHandler_write_space_train_function_definition_info()

void ProtocolConfigMemWriteHandler_write_space_train_function_definition_info

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Train FDI (0xFA) write to two-phase handler.

Write to Train FDI space (0xFA).

ProtocolConfigMemWriteHandler_write_space_train_function_config_memory()

void ProtocolConfigMemWriteHandler_write_space_train_function_config_memory

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Train Fn Config (0xF9) write to two-phase handler.

Write to Train Fn Config space (0xF9).

ProtocolConfigMemWriteHandler_write_space_firmware()

void ProtocolConfigMemWriteHandler_write_space_firmware

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Firmware (0xEF) write to two-phase handler.

Write to Firmware space (0xEF).

ProtocolConfigMemWriteHandler_write_under_mask_space_config_description_info()

void ProtocolConfigMemWriteHandler_write_under_mask_space_config_description_info

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch CDI (0xFF) write-under-mask to two-phase handler.

Write-under-mask to CDI space (0xFF).

ProtocolConfigMemWriteHandler_write_under_mask_space_all()

void ProtocolConfigMemWriteHandler_write_under_mask_space_all

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch All (0xFE) write-under-mask to two-phase handler.

Write-under-mask to All space (0xFE).

ProtocolConfigMemWriteHandler_write_under_mask_space_config_memory()

void ProtocolConfigMemWriteHandler_write_under_mask_space_config_memory

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Config (0xFD) write-under-mask to two-phase handler.

Write-under-mask to Config space (0xFD).

ProtocolConfigMemWriteHandler_write_under_mask_space_acdi_manufacturer()

void ProtocolConfigMemWriteHandler_write_under_mask_space_acdi_manufacturer

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch ACDI-Mfg (0xFC) write-under-mask to two-phase handler.

Write-under-mask to ACDI-Mfg space (0xFC).

ProtocolConfigMemWriteHandler_write_under_mask_space_acdi_user()

void ProtocolConfigMemWriteHandler_write_under_mask_space_acdi_user

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch ACDI-User (0xFB) write-under-mask to two-phase handler.

Write-under-mask to ACDI-User space (0xFB).

ProtocolConfigMemWriteHandler_write_under_mask_space_train_function_definition_info()

void ProtocolConfigMemWriteHandler_write_under_mask_space_train_function_definition_info

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Train FDI (0xFA) write-under-mask to two-phase handler.

Write-under-mask to Train FDI space (0xFA).

ProtocolConfigMemWriteHandler_write_under_mask_space_train_function_config_memory()

void ProtocolConfigMemWriteHandler_write_under_mask_space_train_function_config_memory

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Train Fn Config (0xF9) write-under-mask to two-phase handler.

Write-under-mask to Train Fn Config space (0xF9).

ProtocolConfigMemWriteHandler_write_under_mask_space_firmware()

void ProtocolConfigMemWriteHandler_write_under_mask_space_firmware

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Firmware (0xEF) write-under-mask to two-phase handler.

Write-under-mask to Firmware space (0xEF).

ProtocolConfigMemWriteHandler_write_message()

void ProtocolConfigMemWriteHandler_write_message	(	openlcb_statemachine_info_t *	statemachine_info,
		uint8_t	space,
		uint8_t	return_msg_ok,
		uint8_t	return_msg_fail )

Processes a generic write message (stub)

Generic write message handler. Placeholder.

This stub provides a generic entry point for write command processing.

* @param statemachine_info Pointer to state machine context
* 

* @param space Address space identifier
* 

* @param return_msg_ok Message type for successful write response
* 

* @param return_msg_fail Message type for failed write response
* 

Note

Intentional stub - reserved for future implementation

ProtocolConfigMemWriteHandler_write_reply_ok_message()

void ProtocolConfigMemWriteHandler_write_reply_ok_message	(	openlcb_statemachine_info_t *	statemachine_info,
		uint8_t	space )

Processes a write reply OK message (stub)

Generic write reply OK handler. Placeholder.

This stub handles successful write response messages when acting as a configuration tool.

* @param statemachine_info Pointer to state machine context
* 

* @param space Address space identifier
* 

Note

Intentional stub - reserved for future implementation

ProtocolConfigMemWriteHandler_write_reply_fail_message()

void ProtocolConfigMemWriteHandler_write_reply_fail_message	(	openlcb_statemachine_info_t *	statemachine_info,
		uint8_t	space )

Processes a write reply fail message (stub)

Generic write reply fail handler. Placeholder.

This stub handles failed write response messages when acting as a configuration tool.

* @param statemachine_info Pointer to state machine context
* 

* @param space Address space identifier
* 

Note

Intentional stub - reserved for future implementation

ProtocolConfigMemWriteHandler_write_request_config_mem()

void ProtocolConfigMemWriteHandler_write_request_config_mem	(	openlcb_statemachine_info_t *	statemachine_info,
		config_mem_write_request_info_t *	config_mem_write_request_info )

Processes a write request for Configuration Memory space.

Send write request targeting Config (0xFD) on another node.

Algorithm:

1. Load write reply OK message header
2. Call _write_data to perform the actual write operation

This function handles writes to the primary configuration data storage space. The actual write is delegated to the config_memory_write callback which can implement any storage mechanism (EEPROM, flash, RAM, etc.).

Use cases:

• Writing configuration values to non-volatile storage
• Responding to configuration tool write requests

* @param statemachine_info Pointer to state machine context for message generation
* 

* @param config_mem_write_request_info Pointer to request info with address, byte count, and data buffer
* 

Warning

Both parameters must not be NULL

config_memory_write callback must be implemented

Attention

Writes may affect node behavior - ensure data is validated before writing

See also

_write_data

OpenLcbUtilities_load_config_mem_reply_write_ok_message_header

ProtocolConfigMemWriteHandler_write_request_acdi_user()

void ProtocolConfigMemWriteHandler_write_request_acdi_user	(	openlcb_statemachine_info_t *	statemachine_info,
		config_mem_write_request_info_t *	config_mem_write_request_info )

Processes a write request for ACDI User space.

Send write request targeting ACDI-User (0xFB) on another node.

Algorithm:

1. Load write reply OK message header
2. Use switch statement on requested address to determine SNIP field:
   • CONFIG_MEM_ACDI_USER_NAME_ADDRESS:
     • Call _write_data to write user name
   • CONFIG_MEM_ACDI_USER_DESCRIPTION_ADDRESS:
     • Call _write_data to write user description
   • default (unrecognized address):
     • Load write fail message with OUT_OF_BOUNDS_INVALID_ADDRESS error
3. Set outgoing message valid

This function maps fixed ACDI user addresses to SNIP data fields for user-customizable identification information. Only name and description fields are writeable.

ACDI User writeable fields:

• Name: User-defined node name (e.g. "Front Porch Light")
• Description: User-defined description (e.g. "Controls porch lighting")

Use cases:

• Writing user-defined node name
• Writing user description text
• Customizing node identification

* @param statemachine_info Pointer to state machine context for message generation
* 

* @param config_mem_write_request_info Pointer to request info with address indicating which field and data to write
* 

Warning

Both parameters must not be NULL

config_memory_write callback must be implemented

Attention

User name and description fields have size limits

See also

_write_data

OpenLcbUtilities_load_config_mem_reply_write_ok_message_header

OpenLcbUtilities_load_config_mem_reply_write_fail_message_header

ProtocolConfigMemWriteHandler_write_request_train_function_config_memory()

void ProtocolConfigMemWriteHandler_write_request_train_function_config_memory	(	openlcb_statemachine_info_t *	statemachine_info,
		config_mem_write_request_info_t *	config_mem_write_request_info )

Processes a write request for Train Function Configuration Memory space (0xF9)

Write to Train Fn Config (0xF9): updates in-RAM functions[].

Algorithm:

1. Load write reply OK message header
2. Get train state for the node
3. If train state exists:
   • Iterate over incoming bytes
   • For each byte, calculate function index (address / 2) and byte selector (address % 2)
   • Byte selector 0 = high byte (big-endian), byte selector 1 = low byte
   • Update the corresponding byte of the function value
   • Fire on_function_changed notifier for each function whose bytes were touched
4. Set outgoing message as valid

This function writes function values into the train_state_t.functions[] array from datagram data using big-endian byte order. Function N's 16-bit value occupies byte offsets N*2 (high byte) and N*2+1 (low byte). Bulk writes spanning multiple functions are supported.

After storing the values, this fires the same on_function_changed notifier that Set Function commands use, ensuring consistent application behavior regardless of whether the function was set via Train Control command or via Memory Config write to 0xF9.

Use cases:

• Writing function values from configuration tools (JMRI)
• Bulk writing multiple function values in a single datagram

* @param statemachine_info Pointer to state machine context for message generation
* 

* @param config_mem_write_request_info Pointer to request info with address, data, and byte count
* 

Warning

Both parameters must not be NULL

Node must have train_state initialized via OpenLcbApplicationTrain_setup()

See also

OpenLcbUtilities_load_config_mem_reply_write_ok_message_header