Code Structure

Code Guidelines for README Automation Compatibility

JoinMap Classes

Class Structure

/// <summary>
/// Bridge Join Map for DeviceName
/// </summary>
public class DeviceNameBridgeJoinMap : JoinMapBaseAdvanced
{
    #region Digital

    [JoinName("FeatureName")]
    public JoinDataComplete FeatureName = new JoinDataComplete(
        new JoinData
        {
            JoinNumber = 1,
            JoinSpan = 1
        },
        new JoinMetadata
        {
            Description = "Clear description of what this join does",
            JoinCapabilities = eJoinCapabilities.ToFromSIMPL,
            JoinType = eJoinType.Digital
        });

    #endregion

    #region Analog
    // Analog joins here
    #endregion

    #region Serial
    // Serial joins here
    #endregion

    public DeviceNameBridgeJoinMap(uint joinStart)
        : base(joinStart, typeof(DeviceNameBridgeJoinMap))
    {
    }
}

Best Practices for JoinMaps:

1. Region Organization

   • Always use #region for Digital, Analog, and Serial sections
   • Keep regions in order: Digital, Analog, Serial
   • No joins should exist outside these regions

2. Join Definitions

   [JoinName("ExactFeatureName")]  // Must match property name
   public JoinDataComplete FeatureName = new JoinDataComplete(...)

   • Use consistent naming between JoinName attribute and property
   • Property names should be PascalCase
   • JoinName strings should match property names exactly

3. Join Numbers

   • Start with join 1 (not 0)
   • Keep sequential when possible
   • Group related joins together
   • Document any intentional gaps

4. Join Descriptions

   Description = "Turns feature on/off. FB high when on",

   • Be clear and concise
   • Indicate if it's feedback (FB)
   • Note any special behavior
   • Include value ranges for analogs
   • Document join spans

5. Join Capabilities

   • Use correct eJoinCapabilities:

     ToSIMPL         // For feedback only
     FromSIMPL       // For control only
     ToFromSIMPL     // For both control and feedback

Minimum Framework Version

public class DeviceConfig
{
    public const string MinimumEssentialsFrameworkVersion = "1.2.3";  // Must be defined exactly like this
}

Supported Types

public class PluginFactory : EssentialsPluginDeviceFactory<PluginDevice>
{
    public override void LoadTypesForPlugin()
    {
        TypeNames = new List<string>() {
            "type1",
            "type2"
        };
    }
}

Interface Implementation

// Interfaces should be listed first, followed by base classes
public class DeviceName : EssentialsBridgeableDevice, IInterface1, IInterface2
{
    // Implementation
}

Config Classes

public class DeviceConfig
{
    // Properties that should appear in config examples must be public
    [JsonProperty("propertyName")]
    public string PropertyName { get; set; }

    // Private properties will be excluded from config examples
    private string InternalProperty { get; set; }
}

Common Mistakes to Avoid

1. JoinMap Issues

   // DON'T: Missing region tags
   public JoinDataComplete Join1 = new JoinDataComplete(...);
   
   // DON'T: Inconsistent naming
   [JoinName("one_name")]
   public JoinDataComplete DifferentName = new JoinDataComplete(...);
   
   // DO: Proper region and consistent naming
   #region Digital
   [JoinName("FeatureName")]
   public JoinDataComplete FeatureName = new JoinDataComplete(...);
   #endregion

2. Version Definition

   // DON'T: Wrong property name
   public const string FrameworkVersion = "1.2.3";
   
   // DON'T: Wrong format
   public const string MinimumEssentialsFrameworkVersion = "v1.2.3";
   
   // DO: Correct property name and format
   public const string MinimumEssentialsFrameworkVersion = "1.2.3";

3. Type Names

   // DON'T: Inconsistent casing
   TypeNames = new List<string>() { "Type_One", "typeTwo" };
   
   // DO: Consistent casing
   TypeNames = new List<string>() { "type1", "type2" };

Testing Your Changes

Before committing:

1. Run the README automation script
2. Verify all sections are generated correctly
3. Check join numbers are sequential and grouped logically
4. Verify descriptions are clear and formatted correctly
5. Ensure config example includes all necessary fields

Framework Version Pattern

• Use semantic versioning (MAJOR.MINOR.PATCH)
• Don't include 'v' prefix
• Don't include build numbers
• Don't include prerelease tags in production code

Join Documentation Patterns

Digital Joins

Description = "Action/State description [FB high when condition]"

Analog Joins

Description = "Control description [Range: x-y] [FB mirrors input]"

Serial Joins

Description = "Data format description [Max length: n]"

Join Number Patterns

1. Digital Joins

   • 1-10: Basic controls
   • 11-20: Advanced features
   • 21-30: Feedback
   • 31+: Extended features

2. Analog Joins

   • 1-10: Primary controls
   • 11-20: Secondary controls
   • 21+: Status and feedback

3. Serial Joins

   • 1-10: Basic text/status
   • 11+: Extended data