definitions.lua

---@meta
if _G.__DEFINITIONS_LOADED then
	return
end
_G.__DEFINITIONS_LOADED = true

-- ============================================
-- EventBus
-- ============================================

---@class EventBus
EventBus = {}

---@class EventBus.ScalarEvent
---@field sourceId integer The source ID of the event (-1 = wildcard subscriber)
---@field value integer The current scalar value (int64_t)
---@field previousValue integer The previous scalar value
---@field timestamp integer The timestamp in milliseconds

---@class EventBus.BytesEvent
---@field sourceId integer The source ID of the event (-1 = wildcard subscriber)
---@field value integer[] Array of byte values (1-indexed)
---@field length integer Number of bytes in value array
---@field previousValue integer[] Array of previous byte values (1-indexed)
---@field previousLength integer Number of bytes in previousValue array
---@field timestamp integer The timestamp in milliseconds

---@class EventBus.TextEvent
---@field sourceId integer The source ID of the event (-1 = wildcard subscriber)
---@field value string The current text value
---@field length integer Length of the text value
---@field previousValue string The previous text value
---@field previousLength integer Length of the previous text value
---@field timestamp integer The timestamp in milliseconds

---@class EventBus.StateEvent
---@field sourceId integer The source ID of the event (-1 = wildcard subscriber)
---@field value integer The current state value (int64_t)
---@field previousValue integer The previous state value
---@field timestamp integer The timestamp in milliseconds

---@class EventBus.WifiEvent
---@field connected boolean Whether WiFi is connected
---@field timestamp integer The timestamp in milliseconds

---Subscribe to scalar events (analog/digital sensors, int64 values)
---@param sourceId integer The source ID to subscribe to (-1 = all sources)
---@param callback fun(event: EventBus.ScalarEvent) The callback function
function EventBus.subscribeScalar(sourceId, callback) end

---Subscribe to bytes events (SPI/I2C sensor data)
---@param sourceId integer The source ID to subscribe to (-1 = all sources)
---@param callback fun(event: EventBus.BytesEvent) The callback function
function EventBus.subscribeBytes(sourceId, callback) end

---Subscribe to text events (MODBUS, NMEA, JSON strings)
---@param sourceId integer The source ID to subscribe to (-1 = all sources)
---@param callback fun(event: EventBus.TextEvent) The callback function
function EventBus.subscribeText(sourceId, callback) end

---Subscribe to state events (internal state changes)
---@param sourceId integer The source ID to subscribe to (-1 = all sources)
---@param callback fun(event: EventBus.StateEvent) The callback function
function EventBus.subscribeState(sourceId, callback) end

---Subscribe to WiFi events (connectivity changes)
---@param callback fun(event: EventBus.WifiEvent) The callback function
function EventBus.subscribeWifi(callback) end

-- ============================================
-- Sensor
-- ============================================

---@class Sensor
Sensor = {}

---Get a sensor by ID
---@param id integer The sensor ID
---@return Sensor|nil The sensor object or nil if not found
function Sensor.get(id) end

---Get the total number of sensors
---@return integer The number of sensors
function Sensor.count() end

---Get the sensor name
---@return string The sensor name
function Sensor:getName() end

---Get the sensor ID
---@return integer The sensor ID
function Sensor:getId() end

---Check if the sensor is enabled
---@return boolean True if enabled
function Sensor:isEnabled() end

---Toggle the sensor enable state
function Sensor:toggleEnabled() end

---Check if the sensor is running
---@return boolean True if running
function Sensor:isRunning() end

---Check if the sensor is paused
---@return boolean True if paused
function Sensor:isPaused() end

--- Triggers a measurement; this does not return the measurement value as most sensors work asynchronously; to get the measurement, subscribe to the appropriate EventBus event for this sensor's source ID or use the getLastMeasurement() methods.
function Sensor:measure() end

---Start the sensor
function Sensor:start() end

---Stop the sensor
function Sensor:stop() end

---Pause the sensor
function Sensor:pause() end

---Resume the sensor
function Sensor:resume() end

---Reset the sensor timer
function Sensor:resetTimer() end

-- Get the last scalar measurement; if called directly after measure(), it may return the previous measurement if the new one hasn't arrived yet.
---@return integer|nil The last scalar measurement or nil if none
function Sensor:getLastScalarMeasurement() end

-- Get the last bytes measurement; if called directly after measure(), it may return the previous measurement if the new one hasn't arrived yet.
---@return integer[]|nil The last bytes measurement (1-indexed array) or nil if none
function Sensor:getLastBytesMeasurement() end

-- Get the last text measurement; if called directly after measure(), it may return the previous measurement if the new one hasn't arrived yet.
---@return string|nil The last text measurement or nil if none
function Sensor:getLastTextMeasurement() end

-- ============================================
-- Device
-- ============================================

---@class Device
Device = {}

---Get a device by ID
---@param id integer The device ID
---@return Device|nil The device object or nil if not found
function Device.get(id) end

---Get the total number of devices
---@return integer The number of devices
function Device.count() end

---Get the device name
---@return string The device name
function Device:getName() end

---Get the device ID
---@return integer The device ID
function Device:getId() end

---Get the device state
---@return integer The current state
function Device:getState() end

---Set the device state
---@param state integer The new state value
function Device:setState(state) end

---Check if the device is enabled
---@return boolean True if enabled
function Device:isEnabled() end

---Toggle the device enable state
function Device:toggleEnabled() end

---Start the device
function Device:start() end

-- ============================================
-- Utils
-- ============================================

---@class TimeStruct
---@field year integer Full year (e.g., 2026)
---@field month integer Month (1-12)
---@field day integer Day of month (1-31)
---@field hour integer Hour (0-23)
---@field minute integer Minute (0-59)
---@field second integer Second (0-59)

---@class Utils
Utils = {}

---Get time since boot in milliseconds
---@return integer time_us Time in milliseconds since system boot
function Utils.getTimeSinceBoot() end

---Get current time as a structured TimeStruct
---Returns nil and error message if time is not synchronized (sync is done automatically via SNTP in background)
---@return TimeStruct|nil time Current time as TimeStruct, or nil on error
---@return string|nil error Error message if time retrieval failed
function Utils.getTime() end

---Get current Unix timestamp in seconds
---Returns nil and error message if time is not synchronized (sync is done automatically via SNTP in background)
---@return integer|nil timestamp Current time in seconds since Unix epoch, or nil on error
---@return string|nil error Error message if time retrieval failed
function Utils.getUnixTimestamp() end

---Sleep for specified milliseconds
---@param ms integer Duration to sleep in milliseconds (must be non-negative)
function Utils.sleep(ms) end

-- ============================================
-- Log
-- ============================================

---@class Log
Log = {}

---Log an info message (cyan color)
---@param message string The message to log
function Log.info(message) end

---Log a warning message (yellow color)
---@param message string The message to log
function Log.warn(message) end

---Log an error message (red color)
---@param message string The message to log
function Log.error(message) end

---Log a success message (bright green color)
---@param message string The message to log
function Log.success(message) end