Custom Profiles
Custom Profiles: When Your Device Is Not Built In
Most users should not create a profile. Use a built-in profile when the device is already supported. Create a custom profile only when you have a manufacturer Modbus register map and the device is not already covered.
Use this only for unsupported devices
If your controller, meter, UPS, genset, VFD, heat pump, chiller, or other supported device already has a built-in profile, start there. Custom profiles are the advanced path.
Get the Modbus register mapYou need the manufacturer manual or a known register list. Without it, the profile is guesswork.
Enter the profile headerAdd the name, device type, vendor, model, and normal serial settings.
Add scalar metrics firstStart with useful numbers: voltage, current, frequency, power, RPM, pressure, temperature, fuel, and run hours.
Add statuses and alarmsAdd booleans, enums, and bit flags so users see real names instead of raw numbers.
Test and adjustIf values look wrong, check address, function code, data type, scale, and 0-based vs 1-based addressing.
Custom profile details
NameThe name users select, such as DeepSea DSE7310 or Kirloskar KG645.
Device typeThe category used in setup and YAML: custom, genset, pump, heat_pump, sensor, chiller, vfd, meter, inverter, ups, or protection.
Vendor and modelThe manufacturer and model shown on the device label or manual.
Default Modbus addressThe normal slave ID. Users can override it during gateway setup.
Default serial settingsBaud, parity, data bits, and stop bits. Most simple devices are 9600 8N1, but use the manual.
Polling / telemetry intervalsThe normal read and send intervals for this profile.
Probe candidatesA small set of known-good registers the gateway can use to scan address and baud.
Metric fields
LabelThe readable name users see, for example Battery Voltage.
KeyThe internal name, usually lowercase with underscores, such as battery_voltage.
Metric typeScalar, boolean, enum, bit flags, nibble alarms, or text.
Function codeModbus read type: 1 coil, 2 discrete input, 3 holding register, 4 input register.
AddressThe register address from the manual. Check whether the manual is 0-based or 1-based.
Register countUsually 1 for 16-bit values and 2 for 32-bit or float values.
Data typeHow raw bytes are decoded: u16, s16, u32, s32, float32, or text.
Scale and offsetReadable value = raw value x scale + offset.
Unit and decimalsHow the value is displayed in the UI.
Value mapFor enums, booleans, bit flags, and alarms. This is where raw values become human names.
Use clear labels. Low Oil Pressure is useful. alarm_61 is not.
YAML profile upload
Use YAML when you already have a register map and want to create the profile in one shot. In the console, open Device Profiles, then Import Profile YAML. You can also download YAML from any profile row and use it as a starting point.
profileHeader fields: name, device_type, vendor, model, description, notes, defaults, and probe_candidates. The device_type value must match the setup categories.
defaultsNormal Modbus settings: slave_id, baud, data_bits, parity, stop_bits, poll_interval_minutes, and telemetry_interval_minutes.
metricsList of registers to read. Each row needs key, label, type, function_code, address, count/register_count, and data_type.
value_mapFor enum, boolean, and bit_flags rows. Map raw values or bit positions to readable names.
metadataOptional advanced decoder information. Leave it out unless the profile needs special decoding.
YAML fieldMeaningExample
typeMetric type. Same as metric_type.scalar, enum, boolean, bit_flags, text
function_code / fcModbus read function.3 for holding register, 4 for input register
addressRegister address from the manual.0, 1024, 40001 depending on the manual
countRegister count. Same as register_count.1 for u16, 2 for u32/float32
scale / offsetConversion from raw value.raw 246 with scale 0.1 becomes 24.6
profile:
name: Example Modbus Meter
device_type: meter
vendor: ExampleCo
model: EM-100
defaults:
slave_id: 1
baud: 9600
data_bits: 8
parity: N
stop_bits: 1
poll_interval_minutes: 1
telemetry_interval_minutes: 1
metrics:
- key: voltage_l1
label: Voltage L1
type: scalar
function_code: 3
address: 0
count: 2
data_type: float32
unit: V
decimals: 1
- key: run_state
label: Run State
type: enum
fc: 3
address: 20
data_type: u16
value_map:
0: Stopped
1: Running
- key: alarm_flags
label: Alarm Flags
type: bit_flags
fc: 3
address: 30
data_type: u16
value_map:
0: Low Voltage
1: High Current