MQTT Data Types

CoCoCo supports four distinct data types for device telemetry, each optimized for different use cases and data patterns. Understanding when to use each type is crucial for effective device monitoring and data analysis.

Types of Data

Metrics

Metrics are time series, numerical data that represent measurements at specific points in time.

• Use Case: Temperature readings, pressure measurements, voltage levels, speed readings
• Example: "At time X, the temperature was 23.5°C"
• Storage: Historical time-series data with timestamps
• Analytics: Trend analysis, historical comparisons, predictive modeling

When to use Metrics:

• When you need to track how a value changes over time
• For sensor readings that vary continuously
• When historical analysis and trending are important
• For measurements that have units (temperature, pressure, flow rate)

Toggles

Toggles are boolean, on/off true/false values that represent binary states.

• Use Case: Door open/closed, motor on/off, alarm active/inactive, power enabled/disabled
• Example: "Is the door open or closed?"
• Storage: Current state with state change history
• Analytics: State duration analysis, uptime/downtime tracking

When to use Toggles:

• For binary states (on/off, open/closed, enabled/disabled)
• When you need to track state changes over time
• For alarm conditions or status flags
• When the value can only be true or false

Gauges

Gauges are numerical values that represent the current level or amount of something.

• Use Case: Current stock level, fuel level, battery percentage, queue depth
• Example: "The current stock level is 150 units"
• Storage: Current value with optional history of changes
• Analytics: Current status monitoring, threshold alerting

When to use Gauges:

• For "how much" or "how many" questions about current state
• When you need to know the present value more than historical trends
• For inventory levels, percentages, or quantities
• When the value represents an accumulation that can go up or down

Gauges vs Metrics: While similar, gauges focus on current state while metrics emphasize historical trends. A fuel tank level might be sent as both: a gauge for "current fuel level" and a metric for "fuel consumption rate over time."

Counters

Counters are numerical values that represent cumulative changes over time, typically incrementing.

• Use Case: Parts produced, pages printed, errors encountered, cycles completed
• Example: "We have produced 1,247 widgets total" or "Increment production count by 5"
• Storage: Running total with increment history
• Analytics: Rate calculations, productivity tracking, efficiency metrics

When to use Counters:

• For cumulative totals that generally increase over time
• When you want to track incremental changes rather than absolute values
• For production counts, error tallies, or usage statistics
• When the device reports changes rather than total values

Important: Counters in CoCoCo work by sending incremental changes, not absolute totals. Send +5 to increment by 5, not 1247 as the total count.

Choosing the Right Data Type

Scenario	Recommended Type	Reason
Room temperature sensor	Metric	Continuous value that changes over time, needs trending
Door lock status	Toggle	Binary state (locked/unlocked)
Fuel tank level	Gauge	Current quantity, threshold monitoring important
Production counter	Counter	Cumulative total that increments with each item
Motor speed	Metric	Continuous measurement with units (RPM)
Error condition active	Toggle	Binary alarm state
Current inventory	Gauge	"How many items in stock right now"
Total items processed	Counter	Running total that increases over time

Data Type Combinations

Many real-world scenarios benefit from using multiple data types for the same physical element:

Example: Production Machine

• Metric: machineSpeed - Current RPM for trend analysis
• Toggle: machineRunning - Whether machine is currently operating
• Gauge: currentBatchCount - Items in the current production batch
• Counter: totalItemsProduced - Lifetime production total

Example: Storage Tank

• Metric: tankTemperature - Temperature readings over time
• Toggle: overflowAlarm - Alarm state for overflow condition
• Gauge: currentLevel - Current fill level percentage
• Counter: fillCycles - Total number of fill operations

Data Naming Conventions

Regardless of data type, follow consistent naming patterns:

• Use descriptive names: waterTemperature not temp1
• Include context: mainTankLevel not just level
• Use camelCase or snake_case consistently
• Keep names under 255 characters
• Start with a letter (not number or underscore)

Next Steps

Now that you understand the different data types, learn how to:

1. Publish data using the appropriate MQTT topics for each type
2. Structure your payloads correctly for each data type
3. Implement proper error handling and data validation

CoCoCo supports four distinct data types for device telemetry, each optimized for different use cases and data patterns. Understanding when to use each type is crucial for effective device monitoring and data analysis.

Types of Data

Metrics

Metrics are time series, numerical data that represent measurements at specific points in time.

• Use Case: Temperature readings, pressure measurements, voltage levels, speed readings
• Example: "At time X, the temperature was 23.5°C"
• Storage: Historical time-series data with timestamps
• Analytics: Trend analysis, historical comparisons, predictive modeling

When to use Metrics:

• When you need to track how a value changes over time
• For sensor readings that vary continuously
• When historical analysis and trending are important
• For measurements that have units (temperature, pressure, flow rate)

Toggles

Toggles are boolean, on/off true/false values that represent binary states.

• Use Case: Door open/closed, motor on/off, alarm active/inactive, power enabled/disabled
• Example: "Is the door open or closed?"
• Storage: Current state with state change history
• Analytics: State duration analysis, uptime/downtime tracking

When to use Toggles:

• For binary states (on/off, open/closed, enabled/disabled)
• When you need to track state changes over time
• For alarm conditions or status flags
• When the value can only be true or false

Gauges

Gauges are numerical values that represent the current level or amount of something.

• Use Case: Current stock level, fuel level, battery percentage, queue depth
• Example: "The current stock level is 150 units"
• Storage: Current value with optional history of changes
• Analytics: Current status monitoring, threshold alerting

When to use Gauges:

• For "how much" or "how many" questions about current state
• When you need to know the present value more than historical trends
• For inventory levels, percentages, or quantities
• When the value represents an accumulation that can go up or down

Gauges vs Metrics: While similar, gauges focus on current state while metrics emphasize historical trends. A fuel tank level might be sent as both: a gauge for "current fuel level" and a metric for "fuel consumption rate over time."

Counters

Counters are numerical values that represent cumulative changes over time, typically incrementing.

• Use Case: Parts produced, pages printed, errors encountered, cycles completed
• Example: "We have produced 1,247 widgets total" or "Increment production count by 5"
• Storage: Running total with increment history
• Analytics: Rate calculations, productivity tracking, efficiency metrics

When to use Counters:

• For cumulative totals that generally increase over time
• When you want to track incremental changes rather than absolute values
• For production counts, error tallies, or usage statistics
• When the device reports changes rather than total values

Important: Counters in CoCoCo work by sending incremental changes, not absolute totals. Send +5 to increment by 5, not 1247 as the total count.

Choosing the Right Data Type

Scenario	Recommended Type	Reason
Room temperature sensor	Metric	Continuous value that changes over time, needs trending
Door lock status	Toggle	Binary state (locked/unlocked)
Fuel tank level	Gauge	Current quantity, threshold monitoring important
Production counter	Counter	Cumulative total that increments with each item
Motor speed	Metric	Continuous measurement with units (RPM)
Error condition active	Toggle	Binary alarm state
Current inventory	Gauge	"How many items in stock right now"
Total items processed	Counter	Running total that increases over time

Data Type Combinations

Many real-world scenarios benefit from using multiple data types for the same physical element:

Example: Production Machine

• Metric: machineSpeed - Current RPM for trend analysis
• Toggle: machineRunning - Whether machine is currently operating
• Gauge: currentBatchCount - Items in the current production batch
• Counter: totalItemsProduced - Lifetime production total

Example: Storage Tank

• Metric: tankTemperature - Temperature readings over time
• Toggle: overflowAlarm - Alarm state for overflow condition
• Gauge: currentLevel - Current fill level percentage
• Counter: fillCycles - Total number of fill operations

Data Naming Conventions

Regardless of data type, follow consistent naming patterns:

• Use descriptive names: waterTemperature not temp1
• Include context: mainTankLevel not just level
• Use camelCase or snake_case consistently
• Keep names under 255 characters
• Start with a letter (not number or underscore)

Next Steps

Now that you understand the different data types, learn how to:

1. Publish data using the appropriate MQTT topics for each type
2. Structure your payloads correctly for each data type
3. Implement proper error handling and data validation