Device Factors

Device factors are data point configurations for devices, used to define device data collection and control points.

List Factors

GET /api/v2/devices/{device_id}/factors/

Parameters

None

Response

{
    "success": true,
    "data": [
        {
            "pk": 1,
            "device": 1,
            "unit": 1,             // slave id
            "address": 0,          // address
            "the_type": "temp",    // device type
            "the_type_detail": {   // device type details
                "name": "Temperature",
                "unit": "℃",
                "icon": "https://ums.holdingbyte.com/media/icon/temp.png"
            },
            "data_endian": "big",          // endianness
            "data_endian_display": "Big Endian",  // endianness display
            "data_type": "int16",          // data value type
            "data_type_display": "16-bit Integer", // data type display
            "data_index": 0,               // data read index
            "modbus_type": "holding",      // data source type
            "modbus_type_display": "Holding Register", // data source type display
            "data_factor": 0.1,    // data factor
            "data_delta": 0,       // data delta
            "info": "Temperature sensor",   // notes
            "enabled": true,       // enabled
            "agri_id": "DEVICE001-1-00"  // factor complete ID
        }
    ],
    "error": null
}

Get Factor Details

GET /api/v2/devices/{device_id}/factors/{factor_id}/

Parameters

None

Response

{
    "success": true,
    "data": {
        "pk": 1,
        "device": 1,
        "unit": 1,
        "address": 0,
        "the_type": "temp",
        "the_type_detail": {
            "name": "Temperature",
            "unit": "℃",
            "icon": "https://ums.holdingbyte.com/media/icon/temp.png"
        },
        "data_endian": "big",
        "data_endian_display": "Big Endian",
        "data_type": "int16",
        "data_type_display": "16-bit Integer",
        "data_index": 0,
        "modbus_type": "holding",
        "modbus_type_display": "Holding Register",
        "data_factor": 0.1,
        "data_delta": 0,
        "info": "Temperature sensor",
        "enabled": true,
        "agri_id": "DEVICE001-1-00"
    },
    "error": null
}

Create Factor

POST /api/v2/devices/{device_id}/factors/

Request Parameters

Parameter	Type	Required	Description
unit	integer	Yes	Modbus slave address
address	integer	Yes	Register address
the_type	string	Yes	Device type
data_endian	string	Yes	Data endianness (big/little)
data_type	string	Yes	Data type (e.g., int16/uint16/float)
data_index	integer	Yes	Data read index
modbus_type	string	Yes	Modbus register type (holding/input/coil/discrete)
data_factor	float	No	Data factor for data conversion
data_delta	float	No	Data delta
info	string	No	Notes
enabled	boolean	No	Whether enabled, default true

Response

{
    "success": true,
    "data": {
        // Returns newly created factor information
    },
    "error": null
}

Update Factor

PUT /api/v2/devices/{device_id}/factors/{factor_id}/

Request Parameters

Same as create factor

Response

{
    "success": true,
    "data": {
        // Returns updated factor information
    },
    "error": null
}

Delete Factor

DELETE /api/v2/devices/{device_id}/factors/{factor_id}/

Parameters

None

Response

{
    "success": true,
    "data": null,
    "error": null
}

Control Factor

For switch-type factors, such as IO controllers, Smart Distribution Boxes, you can control the factor's on/off state.

Turn On

POST /api/v2/devices/{device_id}/factors/{factor_id}/on/

Response

{
    "success": true,
    "data": {
        "message": "Operation successful",
        "token": "command_token"
    },
    "error": null
}

Examples

Python

import requests

# Configuration
API_BASE = "https://ums.holdingbyte.com/api/v2"
ACCESS_TOKEN = "your_access_token"

def control_factor(device_id, factor_id, action):
    """Control factor switch
    
    Args:
        device_id: Device primary key ID (integer)
        factor_id: Factor primary key ID (integer)
        action: Action, 'on' or 'off'
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/{factor_id}/{action}/"
    
    response = requests.post(url, headers=headers)
    return response.json()

# Usage examples
device_id = 1  # Device primary key ID
factor_id = 1  # Factor primary key ID

# Turn on factor
result = control_factor(device_id, factor_id, "on")
print(f"Turn on result: {result}")

# Turn off factor
result = control_factor(device_id, factor_id, "off")
print(f"Turn off result: {result}")

cURL

# Turn on factor
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/on/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json"

# Turn off factor
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/off/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json"

Turn Off

POST /api/v2/devices/{device_id}/factors/{factor_id}/off/

Response

{
    "success": true,
    "data": {
        "message": "Operation successful",
        "token": "command_token"
    },
    "error": null
}

Copy Factor

POST /api/v2/devices/{device_id}/factors/{factor_id}/copy/

Parameters

None

Response

{
    "success": true,
    "data": {
        // Returns new factor information after copying, the new factor's name will have "_copy" suffix added to the original factor name,
        // data_index will be automatically incremented
    },
    "error": null
}

Get Factor Data

GET /api/v2/devices/{device_id}/factors/{factor_id}/data/

Parameters

Parameter	Type	Required	Description
device_id	integer	Yes	Device ID
factor_id	integer	Yes	Factor ID
page	integer	No	Page number, starts from 1, default 1
page_size	integer	No	Items per page, default 50
min_timestamp	integer	No	Minimum timestamp (seconds), only returns data after this timestamp, default uses data retention period limit

Example

GET /api/v2/devices/1/factors/2/data/?page=1&page_size=50&min_timestamp=1704758400

Response

{
    "success": true,
    "data": {
        "total": 100,           // Total records
        "data": [
            {
                "agri_id": "DEVICE001-1-00",  // Factor ID
                "v": 25.6,                    // Value
                "t": 1641715200              // UTC timestamp (seconds)
            },
            // ... more data
        ]
    },
    "error": null
}

Notes

• Returns historical data for the specified factor, ordered by time in descending order
• Data retention period is 90 days
• Endpoint has caching, cache time is 5 minutes

Get Data by Factor ID

GET /api/v2/factors/{factor_agri_id}/data/

Parameters

Parameter	Type	Required	Description
factor_agri_id	string	Yes	Factor complete ID, e.g., "xxxxx-1-00"
page	integer	No	Page number, starts from 1, default 1
page_size	integer	No	Items per page, default 50
min_timestamp	integer	No	Minimum timestamp (UTC time, seconds), only returns data after this timestamp, default uses data retention period limit

Example

GET /api/v2/factors/xxxxx-1-00/data/?page=1&page_size=50&min_timestamp=1704758400

Response

{
    "success": true,
    "data": {
        "total": 100,           // Total records
        "data": [
            {
                "agri_id": "DEVICE001-1-00",  // Factor ID
                "v": 25.6,                    // Value
                "t": 1641715200              // UTC timestamp (seconds)
            },
            // ... more data
        ]
    },
    "error": null
}

Notes

• Returns historical data for the specified factor, ordered by time in descending order
• Data retention period is 90 days
• Endpoint has caching, cache time is 5 minutes