docs(mqtt-bridge): complete device config documentation

[groupsky]

Context

PR #341 added device loading from config with good foundational documentation. However, several areas need completion for production-ready documentation.

Current State

• ✅ Configuration examples (RTU and TCP)
• ✅ Field descriptions
• ✅ Connection type documentation
• ✅ Polling configuration overview

Documentation Quality Score: 7/10

Missing Documentation

High Priority

1. Default Values for Optional Fields

Currently missing default values for:

• polling.maxRetries - What's the default? 0? 3?
• polling.retryBackoff - Default backoff strategy?
• connection.parity (RTU) - Default value? "none"?
• connection.dataBits (RTU) - Default value? 8?
• connection.stopBits (RTU) - Default value? 1?
• polling.interval - What happens if polling section is omitted entirely?

Impact: Users must trial-and-error to discover defaults

Suggested fix in README.md:

**Polling configuration:**

- `interval` (required when polling specified) - Polling interval in milliseconds (100-86400000). Default polling interval when section omitted: 5000ms
- `maxRetries` (optional) - Maximum retry attempts (0-100). Default: 3
- `retryBackoff` (optional) - Retry backoff in milliseconds. Default: 1000

2. Validation Error Examples

No examples of common validation errors and how to fix them.

Suggested addition:

### Common Configuration Errors

**Invalid slave ID:**

Error: Invalid configuration: devices.0.slaveId: Number must be less than or equal to 247

Fix: Modbus slave IDs must be 0-247. Check your device's Modbus address.

**Invalid driver name:**

Error: Invalid configuration: devices.0.driver: Driver must be @ya-modbus/driver- or ya-modbus-driver-

Fix: Use the full driver package name. Install with: `npm install @ya-modbus/driver-ex9em`

**MQTT special characters in deviceId:**

Error: Invalid configuration: devices.0.deviceId: Device ID must not contain MQTT special characters (+, #, /, $)

Fix: Use alphanumeric characters and hyphens only for device IDs.

3. Clarify stateDir Status

Current annotation: stateDir (optional) - Directory path for state persistence (future)

Issue: Unclear if this is implemented or not

Options:

• If NOT implemented: Remove from configuration options or move to "Planned Features" section
• If partially implemented: Clarify what works and what doesn't
• If fully implemented: Remove "(future)" annotation

4. Connection Type Field Dependencies

Current docs don't clarify that connection fields depend on type.

Suggested addition:

**Note:** Connection configuration fields depend on the `type`:
- When `type: "rtu"`, use `port`, `baudRate`, `slaveId`, and optional serial settings
- When `type: "tcp"`, use `host`, `port`, `slaveId`
- Mixing connection types in a single device configuration will cause validation errors

Example of INVALID configuration:
```json
{
  "type": "rtu",
  "port": "/dev/ttyUSB0",
  "host": "192.168.1.100",  // ❌ ERROR: 'host' is not valid for RTU
  "baudRate": 9600,
  "slaveId": 1
}

#### 5. Device Loading Order Guarantee

**Suggested addition**:
```markdown
**Device Loading:**
Devices are loaded sequentially in the order specified in the config array. This is important for:
- RTU devices sharing a serial port (first device establishes the transport)
- Predictable startup sequence for troubleshooting

Medium Priority

6. Minimal Configuration Example

Add a minimal working example with only required fields:

{
  "mqtt": {
    "url": "mqtt://localhost:1883"
  },
  "devices": [
    {
      "deviceId": "device1",
      "driver": "@ya-modbus/driver-ex9em",
      "connection": {
        "type": "rtu",
        "port": "/dev/ttyUSB0",
        "baudRate": 9600,
        "slaveId": 1
      }
    }
  ]
}

7. Performance and Security Guidance

Suggested additions:

### Performance Tips
- Polling intervals below 1000ms may impact device responsiveness
- Use separate devices for different polling strategies
- Limit concurrent connections to prevent bus contention (RTU)

### Security Best Practices
- Avoid storing MQTT credentials directly in config files for production
- Consider using environment variables or a secrets manager
- Validate config files before deploying to production

8. Full Example with All Optional Fields

Show an example with every optional field populated to demonstrate full capabilities.

Acceptance Criteria

• All default values documented
• Validation error examples added
• stateDir status clarified
• Connection type dependencies explained
• Device loading order documented
• Minimal example added
• Performance/security guidance added (optional)
• Full example with optional fields added (optional)

Related

• PR feat(mqtt-bridge): add device loading from config (#337) #341 (original implementation)
• Issue Add device loading from config to mqtt-bridge CLI #337 (feature request)

Priority

High - Required for good user experience

[groupsky]

Verified issue status - the requested documentation improvements are still needed.

Current state:

• ✅ Default values exist in validation code (parity: 'none', dataBits: 8, stopBits: 1)
• ✅ Validation tests document error scenarios
• ❌ Default values NOT documented in README.md
• ❌ Validation error examples NOT in documentation
• ❌ Connection type dependencies NOT explained
• ❌ Device loading order NOT documented
• ❌ Performance and security guidance NOT included

The validation code implements the defaults mentioned in this issue, but they need to be documented in the user-facing README.md for proper developer experience. This issue remains valid and actionable.