Version 3.1
January 2026
The CDI Element Mapping Generator is a web-based tool that processes OpenLCB Configuration Description Information (CDI) XML files and automatically generates:
Option 1: Web Server (Recommended)
http://www.mustangpeak.net (or your server
URL)Option 2: Local File
index.htmlcdi-generator.csscdi-generator.jsindex.html to open in your browserNote: If opening locally, some browsers may block external CSS/JS files. If the page looks unstyled, use the web server option or the standalone version (
index_standalone.html).
When you first open the tool, you’ll see:
Visual cue: The drop zone highlights when you drag a file over it.
Before loading, you can optionally enable XML validation:
When to use validation: - First time processing a new CDI file - After making manual edits to XML - Troubleshooting configuration issues - Ensuring OpenLCB CDI 1.4 compliance
When to skip validation: - Processing known-good files - Quick iterations during development - Files already validated by other tools
After loading a file, the Overview section displays key metrics:
Metrics Shown:
Segments: 2
Total Elements: 45
Total Configuration Bytes: 256What these mean: - Segments: Number of separate memory segments in your configuration - Total Elements: Count of all control elements (int, string, eventid, etc.) - Total Configuration Bytes: Total memory required for all configuration data
Click “▼ Segment Details” to expand/collapse this section.
For each segment, you’ll see: - Segment
Name: Descriptive name from <n> tag -
Space: Address space number (typically 253 for
configuration memory) - Origin: Starting address in
hexadecimal - Elements: Number of elements in this
segment - Total Bytes: Memory used by this segment
Example:
Segment: Node Information
Space: 253, Origin: 0x0000 (0)
Elements: 12
Total Bytes: 125This section only appears if memory overlaps are detected.
What it looks like: - Red/pink highlighted header: ⚠ Overlapping Memory Regions Detected - Click to expand/collapse - Table showing all overlapping element pairs
Why overlaps occur: - Multiple segments with same space and origin - Incorrect offset calculations - Manual address assignments that conflict - Copy-paste errors in XML
What to do: 1. Review the overlap table 2. Note which elements conflict 3. Fix your CDI XML: - Adjust segment origins - Fix offset values - Correct replication counts 4. Reload the corrected file
Important: Overlapping memory can cause configuration corruption at runtime. Always fix these before deployment!
Click “▶ Memory Map Table” to expand (collapsed by default).
Columns (left to right):
NODE_INFO_NODE_NAME0x00000<default> tag[not defined] if absentint, string,
eventid, floatNode Info > Settings > TemperatureFeatures:
Search Box: - Type to filter the table in real-time - Searches all columns - Case-insensitive - Example: Type “temp” to find all temperature-related elements
Export CSV: - Click “Export as CSV” button - Downloads the entire table - Opens in Excel, Google Sheets, etc. - Filename includes timestamp
Color Coding: - Different segments shown in different background colors - 8 rotating colors for visual separation - Makes it easy to see segment boundaries
Click “▶ Memory Map Tree View” to expand (collapsed by default).
What it shows: - Hierarchical structure of your configuration - Segments as top-level nodes - Groups as intermediate nodes (expandable) - Elements as leaf nodes
Display Modes:
Single-Line Mode (Default):
▼ Node Information (Segment)
▼ Settings (Group)
└─ TEMP_SENSOR: Temperature - Size = 2 - Addr: 0x0000 (0) - Default: 25
└─ NODE_NAME: Name - Size = 63 - Addr: 0x0002 (2) - Default: "My Node"Multi-Line Mode: Check ☑ Show Details to enable:
▼ Node Information (Segment)
▼ Settings (Group)
└─ TEMP_SENSOR
Breadcrumb: Node Information > Settings > Temperature Sensor
Name: Temperature Sensor
Element Type: int
Size: 2 bytes
Memory Address: 0x0000 (0)
Default value: 25
Min value: -40
Max value: 125Navigation: - Click ▶ or ▼ to expand/collapse nodes - Groups can be expanded/collapsed independently - State is preserved when toggling detail mode
Hexadecimal (0x prefix): - Base-16 numbering system
- Used in most embedded systems - Example: 0x0000,
0x00FF, 0x0100
Decimal (no prefix): - Base-10 numbering system -
Easier for humans to read - Example: 0, 255,
256
Both are shown so you can use whichever is more convenient.
Format: SEGMENT_GROUP_ELEMENT
Example:
NODE_INFO_SETTINGS_TEMP_SENSOR
Breakdown: - NODE_INFO - Segment name -
SETTINGS - Group name - TEMP_SENSOR - Element
name
These become C macros:
#define NODE_INFO_SETTINGS_TEMP_SENSOR_ADDR 0x0000
#define NODE_INFO_SETTINGS_TEMP_SENSOR_SIZE 2Different element types show different formats:
Integer (<int>):
Default: 42
Default: [not defined]String (<string>):
Default: "Device Name"
Default: [not defined]EventID (<eventid>):
Default: 01.02.03.04.05.06.07.08
Default: 00.00.00.00.00.00.00.00Note: EventIDs use dot notation (8 bytes separated by dots)
Float (<float>):
Default: 3.14
Default: [not defined]Green Flags (Good): - ✅ No overlapping memory section - ✅ All segments have different origins (if same space) - ✅ All elements have unique identifiers - ✅ Total bytes is reasonable for your hardware
Red Flags (Problems): - ⚠️ Overlapping Memory Regions section appears - ⚠️ Huge total byte count (indicates replication error) - ⚠️ Elements at unexpected addresses - ⚠️ Missing default values where expected
After processing your XML, four download buttons appear:
Purpose: C header file with memory address definitions
Contents:
/* Auto-generated Configuration Memory Map */
/* Generated: 2026-01-16T12:00:00.000Z */
#ifndef CONFIG_MEM_MAP_H
#define CONFIG_MEM_MAP_H
/* Node Information > Settings > Temperature Sensor */
#define NODE_INFO_SETTINGS_TEMP_SENSOR_ADDR 0x0000
#define NODE_INFO_SETTINGS_TEMP_SENSOR_SIZE 2
/* Node Information > Settings > Node Name */
#define NODE_INFO_SETTINGS_NODE_NAME_ADDR 0x0002
#define NODE_INFO_SETTINGS_NODE_NAME_SIZE 63
#endif // CONFIG_MEM_MAP_HHow to use: 1. Download the file 2. Add to your C
project 3. #include "config_mem_map.h" in your code 4. Use
the macros:
c uint16_t temp; OpenLcb_read_config(NODE_INFO_SETTINGS_TEMP_SENSOR_ADDR, NODE_INFO_SETTINGS_TEMP_SENSOR_SIZE, &temp);
Purpose: Factory reset implementation
config_mem_reset.h contents:
/* Auto-generated Configuration Memory Reset */
#ifndef CONFIG_MEM_RESET_H
#define CONFIG_MEM_RESET_H
#ifdef __cplusplus
extern "C" {
#endif
extern void ConfigMemReset_set_to_defaults(openlcb_node_t *openlcb_node);
#ifdef __cplusplus
}
#endif
#endif // CONFIG_MEM_RESET_Hconfig_mem_reset.c contents: - Implementation of
ConfigMemReset_set_to_defaults() - Writes all default
values to configuration memory - Handles type conversions (int, string,
eventid, float) - Uses big-endian byte ordering
How to use: 1. Download both .h and .c files 2. Add to your C project 3. Call when user requests factory reset: ```c #include “config_mem_reset.h”
// In your reset handler: ConfigMemReset_set_to_defaults(openlcb_node); ```
Purpose: Spreadsheet-compatible documentation
Contents: All table columns in CSV format
How to use: 1. Download the file 2. Open in: - Microsoft Excel - Google Sheets - LibreOffice Calc - Any spreadsheet application 3. Use for: - Documentation - Sharing with team - Importing to other tools - Creating reports
Filename format:
memory_map_YYYY-MM-DD_HH-MM-SS.csv
Goal: Check if your XML is valid and addresses are correct
Steps: 1. Check ☑ Enable XML Validation On Load 2. Load your XML file 3. Review any validation errors 4. Check Overview metrics (reasonable byte count?) 5. Look for overlapping memory warnings 6. Scan the Memory Map Table for unexpected addresses
Common issues to check: - Size attributes (int: 1,2,4,8; float: 2,4,8; string: any) - Replication counts (did you mean 3 or 300?) - Offset values (are gaps intentional?) - Segment origins (do they overlap?)
Goal: Get C files for your embedded project
Steps: 1. Load your CDI XML file 2. Review results (fix any overlaps) 3. Click “Download config_mem_map.h” 4. Click “Download config_mem_reset.h” 5. Click “Download config_mem_reset.c” 6. Add all three files to your C project 7. Include the headers where needed
Goal: Create documentation for your team
Steps: 1. Load your CDI XML file 2. Click “Download Memory Map CSV” 3. Open in Excel or Google Sheets 4. Add to your documentation: - Copy-paste table into Word/Google Docs - Create charts showing memory usage - Share with hardware team - Archive with release notes
Goal: Find why addresses aren’t where expected
Steps: 1. Load your XML file 2. Expand Memory Map Tree View 3. Check ☑ Show Details 4. Navigate to the problematic element 5. Review its full information: - Breadcrumb path (is it nested where you think?) - Memory address (actual location) - Size (is this correct?) - Default value (matches XML?)
Common causes: - Element inside unexpected group - Replication expanding more than expected - Offset value adding extra space - Size attribute incorrect
Goal: See differences between versions
Steps: 1. Load first XML file 2. Click
“Download Memory Map CSV” 3. Save as
version1.csv 4. Reload the page (or hard refresh) 5. Load
second XML file 6. Click “Download Memory Map CSV” 7.
Save as version2.csv 8. Open both in spreadsheet software
9. Use spreadsheet compare features or:
bash diff version1.csv version2.csv
Goal: Locate an element in a large configuration
Steps: 1. Expand Memory Map Table 2. Click in the Search box 3. Type part of the element name 4. Table filters in real-time 5. Clear search to see all elements again
Search tips: - Searches all columns - Case-insensitive - Partial matches work - Try: element name, type, address, value
Symptoms: - White header instead of blue - Full-width layout - No colored borders - Plain text only
Cause: CSS file not loading
Solutions: 1. Check file names:
Must be cdi-generator.css (not styles.css) 2.
Disable ad blocker for this site 3. Hard
refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) 4.
Use standalone version:
index_standalone.html
Symptoms: - Red error messages after loading - Line numbers and XML context shown
Cause: XML doesn’t conform to OpenLCB CDI 1.4 schema
Solutions: 1. Read the error message carefully 2. Note the line number 3. Open your XML in a text editor 4. Go to that line 5. Fix the issue: - Missing required elements - Invalid size attribute - Duplicate child elements - Incorrect attribute names
Common fixes: - Add
<identification> section if missing - Fix
size attribute (int: 1,2,4,8 only) - Remove duplicate
<default> tags - Check space and
origin are numbers
Symptoms: - Red warning section appears - Table shows conflicting elements
Cause: Two or more elements occupy the same address
Solutions:
For multiple segments: 1. Check segment
origin attributes 2. Ensure they don’t overlap (if same
space) 3. Example fix: ```xml
For offset issues: 1. Check offset
attributes on elements 2. Remember: offset is ADDITIVE (adds to running
address) 3. Example fix: ```xml
Symptoms: - Elements not at expected locations - Large gaps in addresses - Addresses seem random
Causes & Solutions:
Cause 1: Replication - Check
replication attribute on groups - Formula:
total_size = instances × single_instance_size - Example:
replication="10" with 20 bytes = 200 total bytes
Cause 2: Offsets - Check offset
attributes - Offset ADDS to current address - Creates gaps in memory -
Example: offset="100" adds 100 to current address
Cause 3: Group Nesting - Elements inside groups get placed sequentially - Check tree view to see actual nesting - Might be in different group than expected
Solution: Use Memory Map Tree View with “Show Details” to trace exactly why each address was assigned.
Symptoms: - Click download buttons, nothing happens - Files download with wrong content
Solutions: 1. Check browser settings: - Allow downloads from this site - Check downloads folder 2. Try different browser: - Chrome, Firefox, Edge all supported 3. Disable download blocking extensions 4. Check disk space (unlikely but possible)
Symptoms: - Tree view flat instead of hierarchical - Groups missing - Only elements shown
Cause: (Should not happen in v3.1, but if it does…)
Solutions: 1. Hard refresh: Ctrl+Shift+R 2. Check
you’re using latest version (v3.1) 3. Verify
cdi-generator.js loaded correctly 4. Check browser console
(F12) for errors
Good practices: - Use meaningful
<n> tags for all elements - Add
<description> tags for documentation - Group related
elements together - Use replication for repeated structures - Comment
complex sections
Example of well-organized XML:
<segment origin="0" space="253">
<n>Node Configuration</n>
<description>Main node settings</description>
<group>
<n>Identification</n>
<description>User-provided node information</description>
<string size="63">
<n>Node Name</n>
<description>Friendly name for this node</description>
<default>My OpenLCB Node</default>
</string>
<string size="64">
<n>Node Description</n>
<description>Detailed description of node function</description>
</string>
</group>
</segment>Before creating your CDI: 1. Calculate total memory needed 2. Plan segment boundaries 3. Decide which elements go in which space 4. Leave room for future expansion 5. Document your layout decisions
Memory allocation tips: - Round segment sizes to nice numbers (128, 256, 512 bytes) - Leave gaps between segments for growth - Use different spaces for different purposes - Start frequently-accessed data at lower addresses
Recommended process: 1. Create/edit CDI XML in text editor 2. Enable validation in generator 3. Load and fix any errors 4. Disable validation for repeated loads 5. Re-enable when making changes
When to validate: - ✅ First load of new XML - ✅ After manual edits - ✅ Before committing to version control - ✅ Before generating production code - ❌ Rapid iteration (slows you down) - ❌ Known-good files (unnecessary)
Tracking changes: 1. Keep XML in version control (git, svn, etc.) 2. Export CSV with each version 3. Store generated .h files with firmware 4. Document changes in commit messages
Good commit message:
Update CDI: Add temperature sensor configuration
- Added temp sensor group with min/max ranges
- Increased segment size from 128 to 256 bytes
- Updated reset defaults for new sensors
- Generated files: config_mem_map.h v2.1Before deploying to hardware: 1. ✅ Load XML in generator 2. ✅ Check for overlaps 3. ✅ Verify total bytes fit in available memory 4. ✅ Review all default values 5. ✅ Download and compile generated .h/.c files 6. ✅ Test factory reset function 7. ✅ Verify addresses match hardware memory map
Q: Do I need to install anything?
A: No! It’s a web application that runs entirely in your browser. Just
open the URL or HTML file.
Q: Does it work offline?
A: Yes, if you download the three files (index.html, cdi-generator.css,
cdi-generator.js) and open them locally.
Q: Is my data sent to a server?
A: No! All processing happens in your browser. Your XML files never
leave your computer.
Q: What browsers are supported?
A: Chrome, Firefox, Safari, and Edge. Any modern browser works.
Q: Can I use this commercially?
A: Check the license terms. The generated .h/.c files are yours to
use.
Q: What CDI specification version is
supported?
A: OpenLCB CDI 1.4
Q: What element types are supported?
A: All standard types: <int>,
<string>, <eventid>,
<float>, <action>,
<blob>, <group>
Q: How does group replication work?
A: Set replication="N" on a <group>
element. The generator creates N copies with sequential addresses and
_REP_0, _REP_1, etc. suffixes.
Q: Can I have multiple segments?
A: Yes! Add multiple <segment> elements. They can
share the same space value if you set different
origin addresses.
Q: What if I don’t specify an
origin?
A: It defaults to 0. Be careful - multiple segments without
origin will overlap!
Q: How is the offset attribute
handled?
A: Offset is ADDITIVE. It adds to the current running address, creating
a gap before that element.
Q: What’s the maximum configuration size?
A: No hard limit in the tool. Your hardware memory is the
constraint.
Q: Can I edit the generated .h files?
A: Not recommended. They’re auto-generated. Edit your XML and regenerate
instead.
Q: What do I do with the .h and .c files?
A: Add them to your C/C++ firmware project. Include the .h files and
compile the .c file with your code.
Q: Why are there three separate files?
A: Follows standard C practice: config_mem_map.h (addresses),
config_mem_reset.h (interface), config_mem_reset.c (implementation).
Q: Can I export to other formats?
A: CSV export is available. Open in Excel/Sheets and save to other
formats (XLSX, ODS, etc.).
Q: How do I import CSV to documentation?
A: Open CSV in Excel/Sheets, then copy-paste into Word/Google Docs, or
use import functions.
Q: Why doesn’t my XML validate?
A: Common issues: wrong size values (int must be 1,2,4,8),
missing <identification>, duplicate tags. Check error
message for specific line.
Q: Why do I see overlapping memory?
A: Multiple segments at same address, incorrect offset
values, or missing origin attributes. Check the overlap
table for specifics.
Q: Why are addresses wrong?
A: Check: group nesting (tree view), replication count, offset
attributes. Use “Show Details” in tree view to trace.
Q: Page looks broken (no styling)?
A: CSS not loading. Try: disable ad blocker, use
index_standalone.html, or check file names are correct
(cdi-generator.css).
Required names: - index.html - Main
HTML file - cdi-generator.css - Stylesheet (NOT
styles.css) - cdi-generator.js - JavaScript
(NOT script.js)
Important: Using generic names like
styles.cssorscript.jsmay cause ad blockers to block them!
Basic Segment:
<segment space="253" origin="0">
<n>My Segment</n>
<int size="1">
<n>My Element</n>
<default>0</default>
</int>
</segment>Group with Replication:
<group replication="4">
<n>Channel Settings</n>
<int size="1"><n>Channel Number</n></int>
<eventid><n>Channel Event</n></eventid>
</group>Element with Offset:
<int size="4"/>
<int size="1" offset="10"/> <!-- 10 bytes after previous element -->Resources: - Main Specification: Technical details and algorithms - Algorithm Definitions: How processing works - Visual Layout Definition: UI component specs - This User Guide: How to use the tool
For Issues: 1. Check this Troubleshooting section 2. Check browser console (F12) for errors 3. Try the standalone version 4. Verify file names are correct 5. Test with example XML
Step 1: Plan Your Configuration
Node needs:
- Name (63 chars)
- Description (64 chars)
- 4 input channels
- 4 output channels
- Each channel: event ID + enabled flagStep 2: Create CDI XML
<?xml version="1.0"?>
<cdi>
<identification>
<manufacturer>My Company</manufacturer>
<model>IO Node v1</model>
<hardwareVersion>1.0</hardwareVersion>
<softwareVersion>1.0</softwareVersion>
</identification>
<segment space="253" origin="0">
<n>Node Info</n>
<string size="63"><n>Node Name</n></string>
<string size="64"><n>Node Description</n></string>
<group replication="4">
<n>Input Channel</n>
<eventid><n>Input Event</n></eventid>
<int size="1"><n>Enabled</n><default>1</default></int>
</group>
<group replication="4">
<n>Output Channel</n>
<eventid><n>Output Event</n></eventid>
<int size="1"><n>Enabled</n><default>1</default></int>
</group>
</segment>
</cdi>Step 3: Validate 1. Save XML as
my_node_config.xml 2. Open CDI Generator 3. Check “Enable
XML Validation” 4. Load the XML file 5. Fix any errors
Step 4: Review Results 1. Check Overview: - Segments: 1 - Total Elements: 10 (2 strings + 4×2 channel elements) - Total Bytes: 199 (63+64+4×9+4×9) 2. Check for overlaps: None (good!) 3. Review table: Addresses sequential (good!)
Step 5: Download Files 1. Click “Download config_mem_map.h” 2. Click “Download config_mem_reset.h” 3. Click “Download config_mem_reset.c” 4. Click “Download Memory Map CSV”
Step 6: Integrate with Firmware 1. Add .h and .c files to project 2. Include headers in main.c 3. Use macros: ```c #include “config_mem_map.h”
// Read node name char name[NODE_INFO_NODE_NAME_SIZE + 1]; OpenLcb_read_config(NODE_INFO_NODE_NAME_ADDR, NODE_INFO_NODE_NAME_SIZE, name); ```
Step 7: Test 1. Compile firmware 2. Flash to
hardware 3. Call ConfigMemReset_set_to_defaults() on first
boot 4. Verify configuration works
Done! Your node is configured and ready.
Version: 3.1
Last Updated: January 2026
Application Version: CDI Element Mapping Generator
v3.1
OpenLCB Specification: CDI 1.4
For technical specifications and implementation details, see: - 01_Main_Specification.md - 02_Algorithm_Definitions.md - 03_Visual_Layout_Definition.md
End of User Guide