Schema Generation Troubleshooting

Common issues and solutions for the schema generation system.

General Issues

Generated Files Not Updating

The generators use content hashing to skip unchanged files. If you need to force regeneration:

# For metrics
rm src/Voltimax.Iot.Contracts/Metrics/Generated/*.g.cs
dotnet run --project tools/Voltimax.Iot.Tools -- generate

# For assets
rm src/Voltimax.Edge.Control.Modbus/Registers/Generated/*.g.cs
dotnet run --project tools/Voltimax.Iot.Tools -- schema asset generate

Build Errors After Regeneration

If the build fails after regeneration:

1. Check the generator console output for errors
2. Verify schema file syntax (JSON/YAML)
3. Look for duplicate identifiers
4. Ensure all referenced types exist

Run with verbose output for more details:

dotnet run --project tools/Voltimax.Iot.Tools -- schema asset generate --verbose

Metrics Generator Issues

Schema Validation Errors

Always validate schemas before generation:

dotnet run --project tools/Voltimax.Iot.Tools -- schema metrics validate

Common causes: unknown unit values (check the Unit enum), duplicate metric names within a registry, and invalid profile names (must be Basic, Standard, or Advanced).

Invalid Metric ID Format

Metric IDs must follow the format key#scope:

active_power#sum    ✅ Valid
active_power_sum    ❌ Invalid (underscore instead of #)
active_power#       ❌ Invalid (empty scope)
#sum                ❌ Invalid (empty key)

Scope Expansion Issues

If scoped metrics aren't generating correctly:

1. Verify the scopes array in the JSON definition
2. Check that scope values are lowercase (l1, not L1)
3. Ensure no conflicting manual definitions

// Correct
{
  "name": "ActivePower",
  "key": "active_power",
  "scopes": ["sum", "l1", "l2", "l3"]
}

// Incorrect - uppercase scopes
{
  "name": "ActivePower",
  "key": "active_power",
  "scopes": ["Sum", "L1", "L2", "L3"]
}

JSON Property Name Conflicts

If you see duplicate JSON property name warnings:

1. Each metric must have a unique key#scope combination
2. Check for overlapping scope definitions
3. Remove any manual JSON property attributes that conflict

Asset Generator Issues

Address Calculation Problems

If register reads return unexpected values, verify the addressing scheme:

Symptoms:

• Reading wrong register
• Values offset by 1 or more
• All zeros or maximum values

Solutions:

Check if the device uses 0-based or 1-based addressing:

protocol:
  addressing: oneBased   # Address 30001 > protocol address 0
  # or
  addressing: zeroBased  # Address 0 > protocol address 0

Verify the register is in the correct YAML section for its Modbus function - see Asset Generation for the function-to-section mapping. Check the device manual for the exact addressing convention.

Byte Order Issues

If values appear garbled or incorrect:

Symptoms:

• Large unexpected values
• Values seem "flipped" or reversed
• Float values are NaN or infinity

Solutions:

Try different byteOrder settings:

protocol:
  byteOrder: bigEndian     # Most common (network order)
  # or
  byteOrder: littleEndian  # Less common

Try different registerPacking for 32-bit values:

protocol:
  registerPacking: wordHighFirst  # High word at lower address
  # or
  registerPacking: wordLowFirst   # Low word at lower address

Test combinations - there are 4 possible configurations:

byteOrder	registerPacking	Description
bigEndian	wordHighFirst	Most common (AB CD)
bigEndian	wordLowFirst	CD AB
littleEndian	wordHighFirst	BA DC
littleEndian	wordLowFirst	DC BA

Scaling Factor Issues

If values are off by a factor of 10, 100, etc.:

Verify the scaling factor in the YAML:

- id: temperature
  address: 30100
  type: int16
  scaling: 0.1  # Raw 250 > 25.0°C

Check the device manual for the correct scale.

Note that integer types with scaling return double.

Enum Reference Errors

If enum references fail to compile:

Verify the enum is defined in the same YAML file:

enums:
  BaudRate:
    2400: 0
    4800: 1
    9600: 2

registers:
  holding:
    settings:
      - id: baudRate
        address: 40001
        type: uint16
        enumRef: BaudRate  # Must match enum name

Enum names become prefixed with device ID: EastronSdm630BaudRate

Enum values starting with numbers get Value prefix: Value2400

YAML Parsing Errors

If the YAML file fails to parse:

1. Check indentation (use spaces, not tabs)
2. Verify required fields are present:
   • device.id
   • device.manufacturer
   • device.model
   • device.assetTypes
3. Ensure lists use proper YAML syntax

# Correct list syntax
assetTypes: [Grid, Battery, Solar]
# or
assetTypes:
  - Grid
  - Battery
  - Solar

# Incorrect
assetTypes: Grid, Battery, Solar

Debugging Tips

Enable Verbose Output

# Assets
dotnet run --project tools/Voltimax.Iot.Tools -- schema asset generate --verbose

# All generators
dotnet run --project tools/Voltimax.Iot.Tools -- generate 2>&1 | tee generate.log

Compare with Working Examples

Reference existing working definitions in schemas/metrics/registries/ (metrics) and schemas/assets/modbus/ (assets).