UPM Utilities

UPM utilities library providing essential timing and delay functions for IoT sensor applications with cross-platform support for Linux and Zephyr operating systems. This utility library offers millisecond to nanosecond precision timing functions, monotonic clock-based duration measurements, and EPA-standard air quality index calculations.

Package Information

• Package Name: upm_utilities
• Package Type: C library
• Language: C
• Platforms: Linux, Zephyr OS
• License: MIT
• Repository: intel-iot-devkit/upm

Core Imports

#include <upm_utilities.h>

The library automatically handles platform detection and uses appropriate timing mechanisms for Linux (POSIX clock functions) or Zephyr (kernel APIs).

Basic Usage

#include <upm_utilities.h>
#include <stdio.h>

int main() {
    // Basic delay operations
    printf("Starting delays...\n");
    upm_delay(1);        // Wait 1 second
    upm_delay_ms(500);   // Wait 500 milliseconds
    upm_delay_us(1000);  // Wait 1000 microseconds
    
    // Timing measurements
    upm_clock_t start = upm_clock_init();
    
    // Do some work...
    upm_delay_ms(100);
    
    // Measure elapsed time
    uint64_t elapsed_ms = upm_elapsed_ms(&start);
    uint64_t elapsed_us = upm_elapsed_us(&start);
    printf("Elapsed: %llu ms, %llu us\n", elapsed_ms, elapsed_us);
    
    // Air quality calculation
    double pm25_concentration = 45.3; // μg/m³
    int aqi = upm_ugm3_to_aqi(pm25_concentration);
    printf("PM2.5: %.1f μg/m³ = %d AQI\n", pm25_concentration, aqi);
    
    return 0;
}

Capabilities

Delay Functions

Cross-platform delay functions supporting multiple time resolutions from seconds to nanoseconds.

void upm_delay(uint32_t time);
void upm_delay_ms(uint32_t time);
void upm_delay_us(uint32_t time);
void upm_delay_ns(uint64_t time);

upm_delay

• Parameters: time - Number of seconds to delay
• Description: Delays execution for the specified number of seconds
• Platform Support: Linux (clock_nanosleep), Zephyr (k_timer/nano_timer)

upm_delay_ms

• Parameters: time - Number of milliseconds to delay
• Description: Delays execution for the specified number of milliseconds
• Platform Support: Linux (clock_nanosleep), Zephyr (k_timer/nano_timer)

upm_delay_us

• Parameters: time - Number of microseconds to delay
• Description: Delays execution for the specified number of microseconds
• Platform Support: Linux (clock_nanosleep), Zephyr (spin-wait using upm_clock)

upm_delay_ns

• Parameters: time - Number of nanoseconds to delay
• Description: Delays execution for the specified number of nanoseconds
• Platform Support: Linux (clock_nanosleep), Zephyr (spin-wait using upm_clock)
• Note: Sub-microsecond accuracy may not be available on all hardware platforms

Usage Example

// Sequential delays with different resolutions
upm_delay(2);           // 2 seconds
upm_delay_ms(1500);     // 1.5 seconds
upm_delay_us(500000);   // 0.5 seconds
upm_delay_ns(100000000);// 0.1 seconds

High-Resolution Timing

Monotonic clock-based timing functions for precise duration measurements unaffected by system time changes.

upm_clock_t upm_clock_init(void);
uint64_t upm_elapsed_ms(const upm_clock_t *clock);
uint64_t upm_elapsed_us(const upm_clock_t *clock);
uint64_t upm_elapsed_ns(const upm_clock_t *clock);

upm_clock_init

• Returns: upm_clock_t - Initialized clock structure for timing measurements
• Description: Initializes a monotonic clock for duration measurements
• Platform Support: Linux (CLOCK_MONOTONIC), Zephyr (sys_cycle_get_32)

upm_elapsed_ms

• Parameters: clock - Pointer to upm_clock_t initialized by upm_clock_init()
• Returns: uint64_t - Number of milliseconds elapsed since clock initialization
• Description: Returns elapsed time in milliseconds since clock was initialized
• Error Handling: Aborts with assertion failure if clock parameter is NULL

upm_elapsed_us

• Parameters: clock - Pointer to upm_clock_t initialized by upm_clock_init()
• Returns: uint64_t - Number of microseconds elapsed since clock initialization
• Description: Returns elapsed time in microseconds since clock was initialized
• Error Handling: Aborts with assertion failure if clock parameter is NULL

upm_elapsed_ns

• Parameters: clock - Pointer to upm_clock_t initialized by upm_clock_init()
• Returns: uint64_t - Number of nanoseconds elapsed since clock initialization
• Description: Returns elapsed time in nanoseconds since clock was initialized
• Note: Sub-microsecond accuracy may not be available on all hardware platforms
• Error Handling: Aborts with assertion failure if clock parameter is NULL

Usage Example

// Measure execution time of operations
upm_clock_t timer = upm_clock_init();

// Perform some sensor operations
sensor_read_data();
process_sensor_data();

// Get timing measurements
uint64_t total_ms = upm_elapsed_ms(&timer);
uint64_t total_us = upm_elapsed_us(&timer);
uint64_t total_ns = upm_elapsed_ns(&timer);

printf("Operation took: %llu ms (%llu μs, %llu ns)\n", 
       total_ms, total_us, total_ns);

Air Quality Index Calculation

EPA-standard air quality index calculation from PM2.5 concentration measurements.

int upm_ugm3_to_aqi(double ugm3);

upm_ugm3_to_aqi

• Parameters: ugm3 - PM2.5 concentration in micrograms per cubic meter
• Returns: int - Calculated Air Quality Index (0-500 scale)
• Description: Converts PM2.5 concentration to AQI based on EPA standards
• Standards: Uses EPA AQI breakpoints from technical assistance document (May 2016)

The function implements the EPA formula: Ip = [(Ihi-Ilow)/(BPhi-BPlow)] × (Cp-BPlow) + Ilow

AQI Scale Reference

Usage Example

// Convert various PM2.5 readings to AQI
double readings[] = {10.5, 25.8, 45.2, 125.0, 275.3};
int num_readings = sizeof(readings) / sizeof(readings[0]);

for (int i = 0; i < num_readings; i++) {
    int aqi = upm_ugm3_to_aqi(readings[i]);
    printf("PM2.5: %.1f μg/m³ → AQI: %d\n", readings[i], aqi);
}

// Output:
// PM2.5: 10.5 μg/m³ → AQI: 44 (Good)
// PM2.5: 25.8 μg/m³ → AQI: 82 (Moderate)  
// PM2.5: 45.2 μg/m³ → AQI: 124 (Unhealthy for Sensitive Groups)
// PM2.5: 125.0 μg/m³ → AQI: 190 (Unhealthy)
// PM2.5: 275.3 μg/m³ → AQI: 325 (Hazardous)

Types

typedef struct timespec upm_clock_t;  // Linux platform
typedef uint64_t upm_clock_t;         // Zephyr platform

upm_clock_t

• Description: Platform-specific time structure for high-resolution timing
• Linux: Uses struct timespec with seconds and nanoseconds fields
• Zephyr: Uses uint64_t hardware cycle counter
• Usage: Created by upm_clock_init(), used with elapsed time functions

Platform Support

The library provides unified APIs with platform-specific implementations:

Linux Platform:

• Uses POSIX clock_nanosleep() for signal-safe delays
• Uses CLOCK_MONOTONIC for reliable timing measurements
• Full nanosecond precision support where hardware allows

Zephyr OS Platform:

• Uses Zephyr kernel timer APIs (k_timer or nano_timer)
• Uses hardware cycle counters for high-resolution timing
• Microsecond delays use spin-wait for sub-millisecond precision

Language Bindings:

• Python and Java bindings available via SWIG interface
• C++ wrapper headers provided but delegate to C implementation

Error Handling

• Delay functions: Return immediately if time parameter is 0
• Timing functions: Abort with assertion failure if clock parameter is NULL
• AQI function: Returns 0 if concentration is outside EPA range (>500.4 μg/m³)
• Signal safety: Linux delays handle interrupted system calls (EINTR) automatically

Build Requirements

• Build System: CMake
• Dependencies: Platform-specific system headers
• Compilation: Mixed C/C++ module (upm_mixed_module_init)
• Linking: May require -lrt on some Linux systems for clock functions