OpenLcbCLib 1.0 Alpha
OpenSource C Library to create OpenLcb/Lcc Nodes
Loading...
Searching...
No Matches
openlcb_config.h
Go to the documentation of this file.
1
38#ifndef __OPENLCB_CONFIG__
39#define __OPENLCB_CONFIG__
40
41#include <stdbool.h>
42#include <stdint.h>
43
44#include "openlcb_types.h"
45
46// =============================================================================
47// Compile-time feature dependency validation
48// =============================================================================
49
50#if defined(OPENLCB_COMPILE_MEMORY_CONFIGURATION) && !defined(OPENLCB_COMPILE_DATAGRAMS)
51#error "OPENLCB_COMPILE_MEMORY_CONFIGURATION requires OPENLCB_COMPILE_DATAGRAMS"
52#endif
53
54#if defined(OPENLCB_COMPILE_BROADCAST_TIME) && !defined(OPENLCB_COMPILE_EVENTS)
55#error "OPENLCB_COMPILE_BROADCAST_TIME requires OPENLCB_COMPILE_EVENTS"
56#endif
57
58#if defined(OPENLCB_COMPILE_TRAIN_SEARCH) && !defined(OPENLCB_COMPILE_EVENTS)
59#error "OPENLCB_COMPILE_TRAIN_SEARCH requires OPENLCB_COMPILE_EVENTS"
60#endif
61
62#if defined(OPENLCB_COMPILE_TRAIN_SEARCH) && !defined(OPENLCB_COMPILE_TRAIN)
63#error "OPENLCB_COMPILE_TRAIN_SEARCH requires OPENLCB_COMPILE_TRAIN"
64#endif
65
66#if defined(OPENLCB_COMPILE_FIRMWARE) && !defined(OPENLCB_COMPILE_MEMORY_CONFIGURATION)
67#error "OPENLCB_COMPILE_FIRMWARE requires OPENLCB_COMPILE_MEMORY_CONFIGURATION"
68#endif
69
70// =============================================================================
71// No-features warning
72// =============================================================================
73
74#if !defined(OPENLCB_COMPILE_EVENTS) && !defined(OPENLCB_COMPILE_DATAGRAMS) && \
75 !defined(OPENLCB_COMPILE_TRAIN)
76#warning "No optional features enabled. This node will only support SNIP identification."
77#endif
78
79// =============================================================================
80// Buffer sanity check
81// =============================================================================
82
83#if (USER_DEFINED_BASIC_BUFFER_DEPTH + USER_DEFINED_DATAGRAM_BUFFER_DEPTH + \
84 USER_DEFINED_SNIP_BUFFER_DEPTH + USER_DEFINED_STREAM_BUFFER_DEPTH) > 126
85#error "Total buffer count exceeds 126 — reduce buffer depths for 8-bit targets"
86#endif
87
88// =============================================================================
89// Verbose compile-time summary (opt-in via OPENLCB_COMPILE_VERBOSE)
90// =============================================================================
91
92#ifdef OPENLCB_COMPILE_VERBOSE
93
94#ifdef OPENLCB_COMPILE_EVENTS
95#pragma message "OpenLcbCLib: EVENTS = ON"
96#else
97#pragma message "OpenLcbCLib: EVENTS = OFF"
98#endif
99
100#ifdef OPENLCB_COMPILE_DATAGRAMS
101#pragma message "OpenLcbCLib: DATAGRAMS = ON"
102#else
103#pragma message "OpenLcbCLib: DATAGRAMS = OFF"
104#endif
105
106#ifdef OPENLCB_COMPILE_MEMORY_CONFIGURATION
107#pragma message "OpenLcbCLib: MEMORY_CONFIGURATION = ON"
108#else
109#pragma message "OpenLcbCLib: MEMORY_CONFIGURATION = OFF"
110#endif
111
112#ifdef OPENLCB_COMPILE_FIRMWARE
113#pragma message "OpenLcbCLib: FIRMWARE = ON"
114#else
115#pragma message "OpenLcbCLib: FIRMWARE = OFF"
116#endif
117
118#ifdef OPENLCB_COMPILE_BROADCAST_TIME
119#pragma message "OpenLcbCLib: BROADCAST_TIME = ON"
120#else
121#pragma message "OpenLcbCLib: BROADCAST_TIME = OFF"
122#endif
123
124#ifdef OPENLCB_COMPILE_TRAIN
125#pragma message "OpenLcbCLib: TRAIN = ON"
126#else
127#pragma message "OpenLcbCLib: TRAIN = OFF"
128#endif
129
130#ifdef OPENLCB_COMPILE_TRAIN_SEARCH
131#pragma message "OpenLcbCLib: TRAIN_SEARCH = ON"
132#else
133#pragma message "OpenLcbCLib: TRAIN_SEARCH = OFF"
134#endif
135
136#endif /* OPENLCB_COMPILE_VERBOSE */
137
158typedef struct {
159
160 // =========================================================================
161 // REQUIRED: Hardware Driver Functions
162 // =========================================================================
163
165 void (*lock_shared_resources)(void);
166
168 void (*unlock_shared_resources)(void);
169
170#ifdef OPENLCB_COMPILE_MEMORY_CONFIGURATION
171
172 // =========================================================================
173 // Memory Configuration (requires MEMORY_CONFIGURATION)
174 // =========================================================================
175
186 uint16_t (*config_mem_read)(openlcb_node_t *openlcb_node, uint32_t address, uint16_t count, configuration_memory_buffer_t *buffer);
187
198 uint16_t (*config_mem_write)(openlcb_node_t *openlcb_node, uint32_t address, uint16_t count, configuration_memory_buffer_t *buffer);
199
206 void (*reboot)(openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info);
207
214 void (*factory_reset)(openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info);
215
226 uint16_t (*config_mem_read_delayed_reply_time)(openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info);
227
236 uint16_t (*config_mem_write_delayed_reply_time)(openlcb_statemachine_info_t *statemachine_info, config_mem_write_request_info_t *config_mem_write_request_info);
237
238#endif /* OPENLCB_COMPILE_MEMORY_CONFIGURATION */
239
240#ifdef OPENLCB_COMPILE_FIRMWARE
241
242 // =========================================================================
243 // Firmware Upgrade Callbacks (requires FIRMWARE)
244 // =========================================================================
245
252 void (*freeze)(openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info);
253
260 void (*unfreeze)(openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info);
261
268 void (*firmware_write)(openlcb_statemachine_info_t *statemachine_info, config_mem_write_request_info_t *config_mem_write_request_info);
269
270#endif /* OPENLCB_COMPILE_FIRMWARE */
271
272 // =========================================================================
273 // OPTIONAL: Core Application Callbacks
274 // =========================================================================
275
279 void (*on_optional_interaction_rejected)(openlcb_node_t *openlcb_node, node_id_t source_node_id, uint16_t error_code, uint16_t rejected_mti);
280
284 void (*on_terminate_due_to_error)(openlcb_node_t *openlcb_node, node_id_t source_node_id, uint16_t error_code, uint16_t rejected_mti);
285
287 void (*on_100ms_timer)(void);
288
291 bool (*on_login_complete)(openlcb_node_t *openlcb_node);
292
293#ifdef OPENLCB_COMPILE_EVENTS
294
295 // =========================================================================
296 // OPTIONAL: Event Transport Callbacks (requires EVENTS)
297 // =========================================================================
298
300 void (*on_consumed_event_identified)(openlcb_node_t *openlcb_node, uint16_t index, event_id_t *event_id, event_status_enum status, event_payload_t *payload);
301
304 void (*on_consumed_event_pcer)(openlcb_node_t *openlcb_node, uint16_t index, event_id_t *event_id, event_payload_t *payload);
305
307 void (*on_event_learn)(openlcb_node_t *openlcb_node, event_id_t *event_id);
308
310 void (*on_consumer_range_identified)(openlcb_node_t *openlcb_node, event_id_t *event_id);
311
313 void (*on_consumer_identified_unknown)(openlcb_node_t *openlcb_node, event_id_t *event_id);
314
316 void (*on_consumer_identified_set)(openlcb_node_t *openlcb_node, event_id_t *event_id);
317
319 void (*on_consumer_identified_clear)(openlcb_node_t *openlcb_node, event_id_t *event_id);
320
322 void (*on_consumer_identified_reserved)(openlcb_node_t *openlcb_node, event_id_t *event_id);
323
325 void (*on_producer_range_identified)(openlcb_node_t *openlcb_node, event_id_t *event_id);
326
328 void (*on_producer_identified_unknown)(openlcb_node_t *openlcb_node, event_id_t *event_id);
329
331 void (*on_producer_identified_set)(openlcb_node_t *openlcb_node, event_id_t *event_id);
332
334 void (*on_producer_identified_clear)(openlcb_node_t *openlcb_node, event_id_t *event_id);
335
337 void (*on_producer_identified_reserved)(openlcb_node_t *openlcb_node, event_id_t *event_id);
338
340 void (*on_pc_event_report)(openlcb_node_t *openlcb_node, event_id_t *event_id);
341
343 void (*on_pc_event_report_with_payload)(openlcb_node_t *openlcb_node, event_id_t *event_id, uint16_t count, event_payload_t *payload);
344
345#endif /* OPENLCB_COMPILE_EVENTS */
346
347#ifdef OPENLCB_COMPILE_BROADCAST_TIME
348
349 // =========================================================================
350 // OPTIONAL: Broadcast Time Callbacks (requires BROADCAST_TIME)
351 // =========================================================================
352
354 void (*on_broadcast_time_changed)(broadcast_clock_t *clock);
355
357 void (*on_broadcast_time_received)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
358
360 void (*on_broadcast_date_received)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
361
363 void (*on_broadcast_year_received)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
364
366 void (*on_broadcast_rate_received)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
367
369 void (*on_broadcast_clock_started)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
370
372 void (*on_broadcast_clock_stopped)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
373
375 void (*on_broadcast_date_rollover)(openlcb_node_t *openlcb_node, broadcast_clock_state_t *clock_state);
376
377#endif /* OPENLCB_COMPILE_BROADCAST_TIME */
378
379#ifdef OPENLCB_COMPILE_TRAIN
380
381 // =========================================================================
382 // OPTIONAL: Train Control Callbacks (requires TRAIN)
383 // All are optional (NULL = use handler defaults).
384 // Notifiers fire AFTER state is updated. Decision callbacks return a value.
385 // =========================================================================
386
387 // ---- Train-node side: notifiers (fire after state updated) ----
388
390 void (*on_train_speed_changed)(openlcb_node_t *openlcb_node, uint16_t speed_float16);
391
393 void (*on_train_function_changed)(openlcb_node_t *openlcb_node, uint32_t fn_address, uint16_t fn_value);
394
396 void (*on_train_emergency_entered)(openlcb_node_t *openlcb_node, train_emergency_type_enum emergency_type);
397
399 void (*on_train_emergency_exited)(openlcb_node_t *openlcb_node, train_emergency_type_enum emergency_type);
400
402 void (*on_train_controller_assigned)(openlcb_node_t *openlcb_node, node_id_t controller_node_id);
403
405 void (*on_train_controller_released)(openlcb_node_t *openlcb_node);
406
408 void (*on_train_listener_changed)(openlcb_node_t *openlcb_node);
409
411 void (*on_train_heartbeat_timeout)(openlcb_node_t *openlcb_node);
412
413 // ---- Train-node side: decision callbacks ----
414
416 bool (*on_train_controller_assign_request)(openlcb_node_t *openlcb_node, node_id_t current_controller, node_id_t requesting_controller);
417
419 bool (*on_train_controller_changed_request)(openlcb_node_t *openlcb_node, node_id_t new_controller);
420
421 // ---- Throttle side: notifiers (receiving replies from train) ----
422
424 void (*on_train_query_speeds_reply)(openlcb_node_t *openlcb_node, uint16_t set_speed, uint8_t status, uint16_t commanded_speed, uint16_t actual_speed);
425
427 void (*on_train_query_function_reply)(openlcb_node_t *openlcb_node, uint32_t fn_address, uint16_t fn_value);
428
431 void (*on_train_controller_assign_reply)(openlcb_node_t *openlcb_node, uint8_t result, node_id_t current_controller);
432
434 void (*on_train_controller_query_reply)(openlcb_node_t *openlcb_node, uint8_t flags, node_id_t controller_node_id);
435
437 void (*on_train_controller_changed_notify_reply)(openlcb_node_t *openlcb_node, uint8_t result);
438
440 void (*on_train_listener_attach_reply)(openlcb_node_t *openlcb_node, node_id_t node_id, uint8_t result);
441
443 void (*on_train_listener_detach_reply)(openlcb_node_t *openlcb_node, node_id_t node_id, uint8_t result);
444
446 void (*on_train_listener_query_reply)(openlcb_node_t *openlcb_node, uint8_t count, uint8_t index, uint8_t flags, node_id_t node_id);
447
449 void (*on_train_reserve_reply)(openlcb_node_t *openlcb_node, uint8_t result);
450
452 void (*on_train_heartbeat_request)(openlcb_node_t *openlcb_node, uint32_t timeout_seconds);
453
454#endif /* OPENLCB_COMPILE_TRAIN */
455
456#if defined(OPENLCB_COMPILE_TRAIN) && defined(OPENLCB_COMPILE_TRAIN_SEARCH)
457
458 // =========================================================================
459 // OPTIONAL: Train Search Callbacks (requires TRAIN + TRAIN_SEARCH)
460 // =========================================================================
461
463 void (*on_train_search_matched)(openlcb_node_t *openlcb_node, uint16_t search_address, uint8_t flags);
464
466 openlcb_node_t* (*on_train_search_no_match)(uint16_t search_address, uint8_t flags);
467
468#endif /* OPENLCB_COMPILE_TRAIN && OPENLCB_COMPILE_TRAIN_SEARCH */
469
470} openlcb_config_t;
471
472#ifdef __cplusplus
473extern "C" {
474#endif
475
489extern void OpenLcb_initialize(const openlcb_config_t *config);
490
498extern void OpenLcb_100ms_timer_tick(void);
499
510extern uint8_t OpenLcb_get_global_100ms_tick(void);
511
520extern openlcb_node_t *OpenLcb_create_node(node_id_t node_id, const node_parameters_t *parameters);
521
528extern void OpenLcb_run(void);
529
530#ifdef __cplusplus
531}
532#endif
533
534#endif /* __OPENLCB_CONFIG__ */
OpenLcb_create_node
openlcb_node_t * OpenLcb_create_node(node_id_t node_id, const node_parameters_t *parameters)
Allocates and registers a new node on the OpenLCB network.
Definition openlcb_config.c:737
OpenLcb_get_global_100ms_tick
uint8_t OpenLcb_get_global_100ms_tick(void)
Returns the current value of the global 100ms tick counter.
Definition openlcb_config.c:161
OpenLcb_run
void OpenLcb_run(void)
Runs one iteration of all state machines.
Definition openlcb_config.c:772
OpenLcb_100ms_timer_tick
void OpenLcb_100ms_timer_tick(void)
Increments the global 100ms tick counter.
Definition openlcb_config.c:784
OpenLcb_initialize
void OpenLcb_initialize(const openlcb_config_t *config)
Initializes the entire OpenLCB stack with one call.
Definition openlcb_config.c:637
openlcb_types.h
Core type definitions, structures, and configuration constants for the OpenLCB library.
event_id_t
uint64_t event_id_t
64-bit Event ID.
Definition openlcb_types.h:340
event_status_enum
event_status_enum
Event status for Producer/Consumer identification messages.
Definition openlcb_types.h:230
configuration_memory_buffer_t
uint8_t configuration_memory_buffer_t[LEN_DATAGRAM_MAX_PAYLOAD]
Configuration memory read/write operation buffer (64 bytes).
Definition openlcb_types.h:365
train_emergency_type_enum
train_emergency_type_enum
Emergency state type for train protocol callbacks.
Definition openlcb_types.h:288
event_payload_t
uint8_t event_payload_t[LEN_EVENT_PAYLOAD]
Event payload data buffer (LEN_EVENT_PAYLOAD bytes).
Definition openlcb_types.h:362
node_id_t
uint64_t node_id_t
48-bit Node ID stored in a 64-bit type (upper 16 bits unused).
Definition openlcb_types.h:359
broadcast_clock_state_t
Complete state for one Broadcast Time clock.
Definition openlcb_types.h:407
broadcast_clock_t
A clock slot with state and subscription flags.
Definition openlcb_types.h:420
config_mem_operations_request_info_TAG
Request info for Get Options / Get Address Space Info commands.
Definition openlcb_types.h:785
config_mem_read_request_info_TAG
Request info for a configuration memory read operation.
Definition openlcb_types.h:799
config_mem_write_request_info_TAG
Request info for a configuration memory write operation.
Definition openlcb_types.h:817
node_parameters_TAG
Complete node configuration parameters (typically const/flash).
Definition openlcb_types.h:562
openlcb_config_t
User configuration for OpenLcbCLib.
Definition openlcb_config.h:158
openlcb_node_TAG
OpenLCB virtual node.
Definition openlcb_types.h:679
openlcb_statemachine_info_t
Complete context passed to protocol handler functions.
Definition openlcb_types.h:743

Copyright (c) 2026 Jim Kueneman all rights reserved. See the License