Current loop input API

Description

The Current loop input API lets you read sensors connected to a 4 to 20 mA current loop interface. You can configure how the interface interprets sensor values and monitor sensor data and hardware status in real time.

You can also set accepted operating ranges with a multi-level threshold system: warning and critical. If a measurement goes outside a configured range, the API triggers an event in the Axis event system.

The API follows common 4 to 20 mA interface practices, including NAMUR NE43 considerations for fault conditions and extended current ranges.

note

This API is optional and might not be available on all products.

Use cases

Configure the current loop interface for a sensor

List or update the configuration used for sensor interpretation and threshold monitoring.

Get all configurations

List all sensor configurations.

{
    "request": {
        "operation": "GET",
        "path": "current-loop.v1.configurations"
    },
    "response": {
        "status": "success",
        "data": [
            {
                "enabled": false,
                "engineeringUnit": "Unit",
                "maxPhysicalValue": 100.0,
                "maxThresholdCritical": 100.0,
                "maxThresholdWarning": 100.0,
                "minPhysicalValue": -100.0,
                "minThresholdCritical": -100.0,
                "minThresholdWarning": -100.0,
                "sensorId": "My-SensorId",
                "sensorName": "Name"
            }
        ]
    }
}

Set all configurations

Update all configuration values.

{
    "request": {
        "operation": "SET",
        "path": "current-loop.v1.configurations['My-SensorId']",
        "data": {
            "enabled": true,
            "engineeringUnit": "°C",
            "maxPhysicalValue": 100.0,
            "maxThresholdCritical": 55.0,
            "maxThresholdWarning": 45.0,
            "minPhysicalValue": 0.0,
            "minThresholdCritical": -15.0,
            "minThresholdWarning": -5.0,
            "sensorId": "My-SensorId",
            "sensorName": "Oven temperature"
        }
    },
    "response": {
        "status": "success"
    }
}

Get a single configuration value

List one configuration value.

{
    "request": {
        "operation": "GET",
        "path": "current-loop.v1.configurations['My-SensorId'].engineeringUnit"
    },
    "response": {
        "status": "success",
        "data": "Unit"
    }
}

Set a single configuration value

Update one configuration value.

{
    "request": {
        "operation": "SET",
        "path": "current-loop.v1.configurations['My-SensorId'].engineeringUnit",
        "data": "°C"
    },
    "response": {
        "status": "success"
    }
}

Monitor sensor status

View live readings and diagnostics from the current loop interface.

Get sensor status

View live status data, including measurements and state.

{
    "request": {
        "operation": "GET",
        "path": "current-loop.v1.status"
    },
    "response": {
        "status": "success",
        "data": {
            "currentValue": 11.579166412353516,
            "loopState": "OK",
            "physicalValue": 24.47525978088379,
            "rawValue": 13895,
            "sensorId": "Sensor-ID",
            "thresholdState": "OK"
        }
    }
}

Get a single status property

View one live status value.

{
    "request": {
        "operation": "GET",
        "path": "current-loop.v1.status['My-SensorId'].physicalValue"
    },
    "response": {
        "status": "success",
        "data": 24.47525978088379
    }
}

Monitor events

Alarm

The current loop threshold alarm is true when the sensor reading crosses a configured warning or critical threshold.

Topic: tns1:CameraApplicationPlatform/tnsaxis:Alarm

Type: Stateful

Nice name: Current loop threshold alarm active

Field name	Type	Nice name	Description	Values
State	string	State	Identifies which threshold was crossed	`Above Upper Critical Threshold` / `Below Lower Critical Threshold` / `Above Upper Warning Threshold` / `Below Lower Warning Threshold`
Active (STATE)	boolean	Active	True when the threshold is exceeded, otherwise false	true/false

Fault

The current loop fault is true when a hardware or wiring issue is detected on the current loop.

Topic: tns1:CameraApplicationPlatform/tnsaxis:Fault

Type: Stateful

Nice name: Current loop fault active

Field name	Type	Nice name	Description	Values
State	string	State	Identifies which fault condition occurred	`Open Circuit` / `Under Range` / `Over Range` / `Short Circuit`
Active (STATE)	boolean	Active	True when the fault condition is present, otherwise false	true/false

Metadata

The current loop data stream updates every 100 ms and carries live measurement values.

Topic: tns1:CameraApplicationPlatform/tnsaxis:Metadata

Type: Stateless

Nice name: Current loop data stream

Field name	Type	Nice name	Description	Values
CurrentValue	double	Current value	Raw loop current in mA	+double+
PhysicalValue	double	Physical value	Current converted to the configured engineering unit	+double+
EngineeringUnit	string	Engineering unit	Engineering unit for the physical value, for example C	+string+

Structure

Objects

current-loop.v1

Root entity for the Current loop input API. It organizes sensor configuration and exposes live diagnostic and measurement data.

current-loop.v1.configurations

The configurations object contains the parameters used to convert loop current into physical values in engineering units, and to define alarm thresholds.

Scaling logic (conversion)

The physical value is calculated with linear interpolation between the 4 mA and 20 mA reference points. minPhysicalValue and maxPhysicalValue define the scale limits.

physicalValue = minPhysicalValue + ((currentValue - 4) * (maxPhysicalValue - minPhysicalValue)) / 16

minPhysicalValue: Expected value at 4 mA.
maxPhysicalValue: Expected value at 20 mA.

Note: Based on NAMUR NE43, if current is in the UNDER_RANGE or OVER_RANGE interval, the same formula is still applied unless a critical fault occurs.

Threshold validation

For a valid configuration, threshold values must follow this order:

minThresholdCritical <= minThresholdWarning <= maxThresholdWarning <= maxThresholdCritical

current-loop.v1.status

The status object provides sensor data and diagnostic results.

Refresh rate: Updated every 100 ms.
State latency: Value changes are immediate, but loopState and thresholdState can include a validation delay.

Data types

LoopStateEnum

Indicates the 4 to 20 mA current loop diagnostic status according to NAMUR NE43.

State	Current range (mA)	Description
`OPEN_CIRCUIT`	< 3.6	Wiring issue (open)
`UNDER_RANGE`	3.6 - 4.0	Normal under range
`OK`	4.0 - 20.0	Normal operation
`OVER_RANGE`	20.0 - 22.0	Normal over range
`SHORT_CIRCUIT`	> 22.0	Wiring issue (short)

ThresholdStateEnum

Indicates threshold status based on the sensor reading converted to engineering units.

State	Condition
`BELOW_LOWER_CRITICAL`	physicalValue <= minThresholdCritical
`BELOW_LOWER_WARNING`	minThresholdCritical <= physicalValue < minThresholdWarning
`OK`	minThresholdWarning <= physicalValue <= maxThresholdWarning
`ABOVE_UPPER_WARNING`	maxThresholdWarning < physicalValue <= maxThresholdCritical
`ABOVE_UPPER_CRITICAL`	physicalValue > maxThresholdCritical

Description​

Use cases​

Configure the current loop interface for a sensor​

Get all configurations​

Set all configurations​

Get a single configuration value​

Set a single configuration value​

Monitor sensor status​

Get sensor status​

Get a single status property​

Monitor events​

Alarm​

Fault​

Metadata​

Structure​

Objects​

current-loop.v1​

current-loop.v1.configurations​

current-loop.v1.status​

Data types​

LoopStateEnum​

ThresholdStateEnum​