Devices Section - Documentation Templates and Guidelines

This README documents the standardized templates and guidelines for all device documentation in the /devices/ section. All device pages must follow these templates for consistency.

Directory Structure

devices/
├── sensors/               # Independent sensor devices
├── gateways/             # Network gateways
├── accessories/          # Device accessories (not standalone)
├── technical-reference/  # CBOR, protocols, specifications
└── wirepas-ecosystem/    # Wirepas-compatible devices
    └── third-party/      # Third-party vendor devices

Device Page Template

All sensor and gateway pages follow this structure:

Required Sections

1. Overview

Brief description of the device, its purpose, and primary use cases.

2. Features

Key features and capabilities. Use comparison tables for platform differences:

| Feature | Haltian IoT | Thingsee IoT |
|---------|-------------|--------------|
| Feature name | Details | Details |

Note: Show ALL features in comparison tables, even when platforms are identical. This provides complete feature visibility.

3. Installation

Step-by-step installation instructions, mounting guidelines, and power requirements. Include platform-specific notes inline (e.g., “In Haltian IoT…” vs “In Thingsee IoT…”).

4. Device Identifiers

Platform-specific device identification codes:

## Device Identifiers

### Thingsee IoT

- **Internal Model Code (IMC):** TSPR04
- **Serial Number Format:** IMC + PSN (Product Serial Number)
- **Example:** TSPR04123456

### Haltian IoT

- **Device Model:** TBD (reverse URL notation)

Note: IMC values are Thingsee IoT specific. Haltian IoT uses reverse URL notation which will be backfilled later. Use “TBD” placeholder for now.

5. Messages

Message schemas extracted from profile documentation. Use tables with only fields actually used by this device:

## Messages

### Measurement Messages

| JSON Field | CBOR Index | Type | Description |
|------------|------------|------|-------------|
| moveCount  | 44         | int  | Count of detected movements |
| profileId  | 1100       | int  | Configuration Profile Id |

Important: Only include fields used by this specific device. Extract from relevant profile documentation ([Presence 13000-13999], [Environment 12000-12999], etc.).

6. Configuration

Link to separate configuration page:

## Configuration

For detailed configuration parameters and examples, see [Device Name Configuration](device-name-configuration).

7. Device-Specific Features (if applicable)

Unique features not covered in standard template. Examples:

RADAR: Memory bank configuration
Gateway: Network topology management
Special operating modes

Use this section for any device-specific functionality that doesn’t fit the standard template.

8. Troubleshooting

Common issues and solutions.

Configuration Page Template

All devices with configurable parameters get a separate [device-name]-configuration.md file, even if configuration options are minimal (for consistency).

Required Sections

1. Overview

Brief introduction to device configuration capabilities.

2. Intervals

Configuration for measurement and reporting timing:

## Intervals

| Parameter | CBOR Index | Range | Default | Description |
|-----------|------------|-------|---------|-------------|
| measurementInterval | 256 | 1-3600s | 60s | How often sensor reads values |
| reportInterval | 258 | 1-86400s | 300s | How often data is sent |

3. Thresholds

Trigger thresholds and hysteresis values:

## Thresholds

| Parameter | CBOR Index | Range | Default | Description |
|-----------|------------|-------|---------|-------------|
| impactThresholdMin | 259 | 0-2000 mG | 200 mG | Lower threshold for impact detection |
| temperatureHysteresis | 275 | 0-100 | 5 | Temperature change threshold (0.1°C units) |

4. Modes

Sensor operating modes:

## Modes

| Parameter | CBOR Index | Values | Default | Description |
|-----------|------------|--------|---------|-------------|
| accelerometerMode | 262 | 0-3 | 0 | 0=Off, 1=Impact, 2=Movement, 3=Both |

5. Advanced Settings

Less frequently used configuration parameters.

6. Examples

Practical configuration examples with both JSON and CBOR hex formats:

## Examples

### Set Measurement and Reporting Intervals

**JSON Format:**
```json
{
  "tsmId": 1500,
  "tsmEv": 30,
  "transactionId": 1485925806,
  "measurementInterval": 30,
  "reportInterval": 300
}

CBOR Hex:

a5 01 19 05 dc 02 18 1e 18 19 1a 58 91 6d ae 19 01 00 18 1e 19 01 02 19 01 2c


**Note:** Only document parameters found in existing documentation. Do not infer or add undocumented parameters.

## Accessory Page Template

Accessories follow a simplified template:

### Required Sections

1. **Overview** - What the accessory is and its purpose
2. **Features** - Key capabilities
3. **Installation** - How to attach to compatible devices
4. **Compatibility** - Which sensors/devices it works with
5. **Configuration** - Link to configuration page if applicable

## Table Formats

### Message Field Table

```markdown
| JSON Field | CBOR Index | Type | Description |
|------------|------------|------|-------------|

JSON Field: Semantic name used in JSON format
CBOR Index: Numeric index used in CBOR encoding
Type: Data type (int, float, string, buffer, etc.)
Description: Field purpose and units

Configuration Parameter Table

| Parameter | CBOR Index | Range | Default | Description |
|-----------|------------|-------|---------|-------------|

Parameter: Configuration parameter name
CBOR Index: Numeric index for configuration
Range: Valid value range
Default: Factory default value
Description: Parameter purpose and units

Comparison Table

| Feature | Haltian IoT | Thingsee IoT |
|---------|-------------|--------------|

Show ALL features, even when platforms are identical. This provides complete visibility and allows for future platform divergence.

Content Guidelines

Two-Pass Content Creation

First Pass - Draft Merge: Merge all source documents section-by-section
Second Pass - LLM Analysis: Apply analysis for:
- Clarity: Clear, concise technical language
- Accuracy: Verify all facts and specifications
- Completeness: Include all relevant details
- Redundancy Removal: Eliminate duplicate information

Conflict Resolution

When source documents contain conflicting information:

Flag for human review - Do not make assumptions
Document the conflict - Note which sources disagree
Provide context - Explain which source is newer/more authoritative if known

Platform Differences

Use inline notes: “Available in Haltian IoT and Thingsee IoT”
Use inline notes: “Haltian IoT only” or “Thingsee IoT only”
Use comparison tables for feature differences
Never use the term “legacy” - always refer to platforms by name

Missing Information

For third-party devices or incomplete documentation:

Use simple text: “Information not available”
Do not use alert boxes, callouts, or special formatting
Maintain template structure with unavailable sections noted

Migration Process

Content Sources

For each device, merge content from:

Haltian IoT device pages (/docs/haltian-iot/devices/)
Thingsee IoT device pages (/docs/thingsee-iot/devices/)
Profile documentation (/docs/thingsee-iot/api/profiles/)
Old support site (old_support_site/devices_old/)

Quality Criteria

All migrated content must be:

Technically accurate - This is a technical fact page
Complete - All relevant information included
Clear - Easy to understand for technical users
Consistent - Follows template structure
Non-redundant - No duplicate information

Cross-References

To Device Pages

From profile documentation, use:

See [Thingsee PRESENCE](/devices/sensors/thingsee-presence) for full documentation →

To Configuration Pages

From device pages, use:

See [Thingsee PRESENCE Configuration](thingsee-presence-configuration) for detailed configuration →

To CBOR Guide

From any page referencing message formats:

See [CBOR-to-JSON Conversion Guide](/devices/technical-reference/cbor-json-conversion) for encoding details →

File Naming

Device pages: thingsee-presence.md, haltian-radar.md
Configuration pages: thingsee-presence-configuration.md
Use lowercase with hyphens
Include brand prefix (thingsee-, haltian-)

Common Pitfalls

❌ Don’t:

Use “legacy” to describe Thingsee IoT
Include undocumented configuration parameters
Make assumptions about conflicting information
Use alert boxes for “Information not available”
Include CBOR indexes for fields not used by device

✅ Do:

Use platform names (Haltian IoT, Thingsee IoT)
Only document parameters from existing docs
Flag conflicts for human review
Use simple text for unavailable information
Extract only device-specific message fields

Maintenance

This README and templates may be updated as patterns emerge during migration. Changes should maintain consistency with already-migrated devices.