Provisioning a Card 

Table of contents
  1. Introduction
  2. How Provisioned Identity Interacts with CDI and Discovery
    1. CDI ↔ Identity Sync (Conceptual Flow)
  3. Example 1 – Provisioning a Card via the Node Card (Node Bus Hub)
  4. Example 2 – Provisioning ESP32-Based Cards Directly (No Node Card Required)
  5. Troubleshooting Identity & Discovery

Introduction

Each card can be provisioned with:

  • a card Type (ID)
  • a Reference ID (builder-defined tag, e.g. BOD-001)
  • a short Version tag (e.g. 1A or 1.0)
  • a Description

This lets the Node Card verify the installed card against the CDI configuration. For example, if the CDI expects this card on BUS A with address offset 4, the Node firmware can confirm that during installation.

Tip: For an overview of using the serial monitor (?, I, T, P), see
Using the Serial Monitor for Help & Testing.

How Provisioned Identity Interacts with CDI and Discovery

Provisioning a card stores its identity in a small DPROM/EEPROM or on-board ESP32 NVS.
When the Node scans the I²C network (the Node Cluster), it uses this identity together with the CDI configuration to keep everything in sync.

Key Principle – Installer First
The installer’s hardware choices (DIP/address switches and which slot the card is plugged into) are treated as authoritative.
The Node keeps the CDI in sync with what it discovers on the bus so you do not have to crawl under the layout to change switches.

When you provision a card, the Node applies the following rules:

  1. Provisioned identity overrides CDI fields (when discovered)
    • If a card provides identity via DPROM/EEPROM/ESP32 NVS and is discovered on the I²C bus, the Node treats that identity as authoritative.
    • The CDI’s RefId, Bus, Offset, and (when empty) Description are updated to reflect what the hardware reports and where it is actually installed.
    • Physical Bus/Offset (set by switches and the card’s placement in the Node Cluster) always wins; CDI is updated to match.
  2. Provisioning is recommended for easier plug-and-play
    • A provisioned card becomes self-describing: it carries its Type, RefId, Version, and Description.
    • During discovery, the Node can immediately determine:
      • What card type it is.
      • Which specific card it is (RefId/FID).
      • Where it is installed (Bus/Offset).
    • This makes card replacement, relocation, and troubleshooting much easier.
  3. Unprovisioned cards still work and can still update CDI
    • If a card has no identity provisioned, the Node can still detect it by probing the MCP / device at that Bus/Offset.
    • When a new unprovisioned card is discovered at a Bus/Offset, the Node can still update the CDI Bus/Offset to match the physical location.
    • The only difference is that no RefId or Description is auto-filled from the card itself.
  4. Provisioned and unprovisioned cards can be added at any time
    • You can insert, replace, or move provisioned and unprovisioned cards on the I²C bus at any time (with power off recommended for best reliability).
    • On each discovery pass:
      • Provisioned cards supply identity and location.
      • Unprovisioned cards still contribute their Bus/Offset.
      • The Node updates CDI to track the hardware, and reports conflicts such as duplicate addresses.

Recommendation
For a clean plug-and-play experience, provision cards whenever practical.
Unprovisioned cards are fully supported, but you lose automatic naming and version tracking.

CDI ↔ Identity Sync (Conceptual Flow)

The diagram below shows, for a single card slot, how CDI information and provisioned card identity are reconciled.

stateDiagram-v2
    [*] --> CDI_Only: CDI has config\n(no identity yet)
    [*] --> Identity_Only: Card discovered\nDPROM provisioned\nCDI blank

    CDI_Only --> Synced: Card discovered\nidentityPresent == true
    Identity_Only --> Synced: CDI fields\nfilled from identity

    CDI_Only --> HW_Only: Card not responding\nor removed
    Synced --> HW_Only: Card removed\nCDI not yet cleared

    Synced --> Synced: Card moved\n(discovery updates\nCDI Bus/Offset)

    Synced --> Replaced: FID mismatch\n(new card in slot)

    Synced: CDI + Identity aligned\n(Bus/Offset + RefId)
    CDI_Only: CDI-only config\n(no DPROM identity)
    Identity_Only: Card-only identity\n(CDI not configured)
    HW_Only: CDI expects card\nbut hardware missing
    Replaced: Slot has a different\ncard than CDI expects

Example 1 – Provisioning a Card via the Node Card (Node Bus Hub)

Use this method for the PWM Card and all of the MCP-based I/O cards. For the cards that have an ESP32 installed, you can use this method or the method shown below in Example 2, which is a little simpler.

  1. Cable & power
    • Insert the card you want to provision (e.g. Output Card) into the Node Bus Hub.
    • Ensure only this one card is connected while provisioning.
    • Set the card’s communication BUS (BUS A or BUS B) and address switches to your chosen offset (0–7).
    • Power the system.
  2. Open a serial monitor
    • Connect to the Node Card’s ESP32 at 115200 baud (Arduino IDE Serial Monitor, YAT, WebSerial, etc.).
  3. Run the provisionmer
    • Type P and press Enter.
    • The Node scans both buses and reports the card it found.
    • When prompted:
      • Select the Card Type from the list (e.g. Button, Output, etc.).
      • Enter the card’s Reference ID (e.g. BOD-001 or Yard-A-01). This value is stored in the card’s identity and is also used in the CDI.
      • Enter a short Version tag (up to 3 characters, e.g. 1.0). It is recommended to use the version printed on the PCB bottom.
      • Enter a Description (e.g. Mainline Zone 3 – Block 1). This value is used in the CDI and in status displays.
    • The monitor will confirm success once the card’s DPROM/EEPROM has been written and verified.
  4. Notes
    • Provision one card at a time.
    • Ensure power is on and all cables are firmly connected.
    • Make sure both the Node Card and this card are fully seated in the Hub.
    • Set the card’s COMM BUS and COMM ADDR selections to a unique bus and offset position (0–7).
    • If the card isn’t found:
      • Reseat the cards and power-cycle.
      • Confirm the small EEPROM / DPROM IC is installed and oriented correctly.
      • Try different bus and address settings to help diagnose switch or soldering issues.

Example 2 – Provisioning ESP32-Based Cards Directly (No Node Card Required)

The following cards have their own ESP32 on-board and can be provisioned without a Node Card or Node Bus Hub:

  • Audio Card
  • BSD Card
  • UOD Card
  • DCC Card
  • Sound Card

After you have built the card and loaded its firmware, you can provision its identity using only:

  • the card itself,
  • a USB cable, and
  • a serial monitor.
  1. Power the card
    • Mount the ESP32 on the card as designed.
    • Connect the card’s ESP32 USB port to your computer.
    • The USB connection provides power; the Node Bus Hub is not required for provisionming.
  2. Open a serial monitor
    • Open a serial terminal to the card’s ESP32 at 115200 baud (Arduino IDE Serial Monitor, YAT, etc.).
    • Press Reset on the ESP32 if needed to see the startup banner.
  3. Run the on-card provisionmer
    • Type P and press Enter.
    • The card’s firmware runs the same provisionming flow used by the Node:
      • It prepares its Card Info record in local NVS (non-volatile storage).
    • When prompted:
      • Confirm you want to provision this card.
      • Select / confirm the Card Type (e.g. BSD, Audio, UOD, DCC, Sound).
        • The card’s firmware will auto-fill the correct type for that card.
      • Enter the Reference ID (e.g. BSD-001, AUDIO-01).
      • Enter a short Version tag (up to 3 characters, e.g. 1.0). It is recommended to use the version printed on the PCB bottom.
      • Enter a Description (e.g. Booster District Short Detection, Yard Audio Player 1).
    • The card writes this information into its on-board NVS and confirms success.
  4. Verify (optional)
    • These ESP32-based cards also include a self-test or T / SELF TEST command.
    • Running the self-test may:
      • Confirm that Card Info is present and matches the expected Card Type.
      • Print the stored Reference ID, Version, and Description.
  5. Install the card on the layout
    • Once provisioned, insert the card into the Node Bus Hub along with a Node Card as usual.
    • The Node Card can now:
      • Read the card’s identity over I²C.
      • Verify that the card on this bus/offset matches the CDI configuration.
    • You do not need to re-run provisioning from the Node unless you want to change the stored information.

Troubleshooting Identity & Discovery

When working with provisioned and unprovisioned cards on the Node Cluster, the Node’s discovery and status logic can help diagnose issues quickly.

Tip – Watch for [W] vs [E] markers in serial output The Node’s serial diagnostics can tag lines with:

  • [W] for warnings (for example, a configured card with NO_IDENTITY), and
  • [E] for errors (for example, a card that is NOT_CONNECTED or has a conflicting configuration).

Use the following checklist when cards are not behaving as expected:

  1. Card is configured in CDI but not detected
    • Check that the card is fully seated in the Node Bus Hub.
    • Verify the COMM BUS and COMM ADDR switches are set to the intended Bus/Offset.
    • Confirm the Node’s I²C cables are correct and firmly plugged in.
    • In serial output, look for:
      • [E] ... NOT_CONNECTED – CDI expects a card, but the hardware did not respond.
  2. Card works but shows “NO_IDENTITY”
    • This typically means:
      • The card is present and responding, but
      • The DPROM/EEPROM or on-board identity is not provisioned (or not present).
    • The card can still be used.
    • To enable full plug-and-play:
      • Provision the card using Example 1 (Node-led) or Example 2 (ESP32-led), then
      • Allow the Node to rescan the cards so the CDI can be updated.
  3. CDI Bus/Offset does not match where the card is actually installed
    • Move the card to the desired slot and set its address switches.
    • Run a discovery pass (or trigger a rescan from the Node’s serial menu).
    • The Node will:
      • Discover the card at its actual Bus/Offset, and
      • Update the CDI to match that physical location (installer-first policy).
  4. Replacing a card with a different one in the same slot
    • If the new card has a different identity (different RefId/FID):
      • The Node may detect this as a replacement.
      • CDI RefId and logic may no longer match the new card’s role.
    • Recommended steps:
      • Provision the new card with its own identity (Type, RefId, Version, Description).
      • Review and update CDI logic and descriptions to match the new card’s purpose.
  5. Mixed provisioned and unprovisioned cards
    • This is fully supported:
      • Provisioned cards auto-fill CDI RefId/Description and are easiest to track.
      • Unprovisioned cards are still discovered by Bus/Offset, and the CDI can be updated accordingly.
    • Over time, you can gradually provision more cards to enhance plug-and-play behavior without disrupting the existing layout.

If issues persist, use the Node’s serial menu (?, I, T, P) to review card status, identities, and test results. This provides a clear picture of which cards are present, how they are configured, and whether identity has been provisioned.

Last updated on: December 17, 2025 © 2025 Pat Fleming