MFi-Custom Sensors
From Ubiquiti Wiki
Configuration
Custom device types are defined by placing definitions in a file named custom.json, located in <mFi root>/dl directory.
Ubiquiti mFi/dl/custom.json
The file format is JSON, with each type of device being an entry in the JSON object, indexed by the name of the device type.
{
"sensor 1 name" : {
....
},
"sensor 2 name" : {
....
},
....
"sensor n name" : {
....
}
}
After changing the custom.json file, the server must be restarted.
Once a new device type is defined, the device name will be available as an option in the device configuration pull-down menus for the corresponding port types (RJ45 or Terminal Block).
Errors in the file will generate an error message in the server log. (ex: <launcher> ERROR SystemService - Unable to parse custom sensor bundle data.”
Defining a custom device with the same name as a predefined device will override the predefined definition with the new custom definition.
To help track down errors in the custom.json file, try running the contents through a JSON Lint validator: http://jsonlint.com/
Pins
| Label | Function | Overview | Ports |
|---|---|---|---|
| I | Input | 0v-2v = off, > 4v-24v = on | RJ45 1&5, TB 7 |
| O | Output | 0, 5v, 12v or 24v | RJ45 2&8, TB 8 |
| P | Power | 0, 12v, 24v | RJ45 4, TB 6 |
| G | Ground | Common | RJ45 7, TB 3 |
| A+ | Analog+ | differential analog, positive | RJ45 3, TB 5 |
| A- | Analog- | differential analog, negative | RJ45 6, TB 4 |
| RTD | RTD | Resistance Temperature Detector | TB 1&2 |
Power (P)
Current draw of the connected devices must be kept under 40 mA total, per output voltage (5v, 12v, 24v). This includes current on both the power pins and the output pins (combined).
Analog (A+,A-)
Analog is differential, and can vary between -2.048v and +2.048v. Applying larger voltages, even temporarily (such as during a sensor hot plug) can permanently damage the Analog Input!
To connect a single-ended device, the A- pin can be grounded. Then the input voltage can vary between 0 and +2.048v.
To measure voltages higher then +2.048v, and voltage divider circuit can be used.
To measure 0-20mA or 4-20 mA current loops, a burden resistor can be used (such as 100 Ohms).
RTD
The Resistance Temperature Detector is type PT100 , with an alpha coefficient of 0.00385 ohms/ohm/°C. The RTD interface is 2-wire. Temperature measurements can vary between -50°C and +250°C.
RJ45 Pinout
Example Sensors
ColliHigh Illuminometer
- Model: ZD-M-VB
- Range: 0-10,000 lux
- Output: 0-5 volts
- Power: 24 volts
- Accuracy: +- 7%
A voltage divider circuit is used to reduce the voltage to the 2 volt range.
A- is tied to ground since the sensor is single-ended.
Sensor Definition
"ColliHigh Illuminometer" : {
"desc" : "Collihigh Illuminometer. 24V power, output 0~5V DC",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"pwr_volt" : 24,
"rep_analog" : 1,
"default_tag" : "light",
"analog_tag" : "light",
"conversion" : "xyz*5000",
"unit" : "lux",
"precision" : 2
}
MaxDetect Temperature and Humidity Sensor
- Model: MQ3020
- Range: variable, -20 - 80 C setting used in this example
- Output: 4-20mA
- Power: 24 volts
- Accuracy: +-0.3 C, +-2% RH
A burden resistor is used to convert the current to a voltage.
Sensor Definition
"MaxDetect Outdoor Temperature Sensor" : {
"desc" : "MaxDetect MQ3020. 24V power, output 4-20mA. Jumpered for -20 to +80C.",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"pwr_volt" : 24,
"rep_analog" : 1,
"default_tag" : "temperature",
"analog_tag" : "temperature",
"conversion" : "-31.11+xyz*55.55",
"unit" : "CELSIUS",
"precision" : 3
}
LM35 Temperature Sensor IC
- Range: 0-100 C
- Output: 1 C / 10mV
- Power: 5 volts
Sensor Definition
"LM35" : {
"desc" : "National Semiconductor LM35 temperature sensor. 5V power output.",
"conversion" : "xyz*100",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 5,
"rep_analog" : 1,
"default_tag" : "temperature",
"analog_tag" : "temperature",
"sum_label" : "degreeHours",
"unit" : "CELSIUS",
"precision" : 2
}
MaxSonar UltraSonic Range Finder
- Model: LV-MaxSonar-EZ4 (MB1040)
- Range: 254 inches
- Output: 1 inch / 9.8mV
- Power: 5 volts
- Accuracy: 1 inch
Without Voltage Divider
This configuration does not use a voltage divider - so it maxes out at 204 inches, which doesn't reach the true 254 inch range of the sensor.
Sensor Definition
"MaxSonar Ultrasonic Range" : {
"desc" : "LV-MaxSonar-EZ4: MB1040 (5v power, 17' range)",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 5,
"rep_analog" : 1,
"default_tag" : "distance",
"analog_tag" : "distance",
"conversion" : "xyz*8.5",
"unit" : "feet",
"precision" : 2
}
With Voltage Divider
"MaxSonar Ultrasonic Range" : {
"desc" : "MaxBotix MaxSonar EZ LV4 (0-254 inches) - with voltage divider",
"conversion" : "xyz*21.33",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 5,
"rep_analog" : 1,
"default_tag" : "distance",
"analog_tag" : "distance",
"unit" : "ft",
"precision" : 2
}
Tempco 4 Port Relay Board (MRB-4-12VDC)
http://www.temcocontrols.com/ftp/pdf/MRB.pdf
Turning on an mPort output applies 12V DC to the relay, closing the connection between the 2 pins of corresponding output (K1, K2, K3 or K4).
Sensor Definition
Just select “Output 12V” (per port)
PowerSwitch Tail II
http://www.powerswitchtail.com/Pages/default.aspx
Sensor Definition
Just select “Output 5V”
Seeedstudio Light Sensor
"Light Sensor (Seeedstudio)" : {
"desc" : "Seeedstudio light sensor",
"conversion" : "xyz*5",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 5,
"rep_analog" : 1,
"default_tag" : "lux",
"analog_tag" : "lux",
"unit" : "lux",
"precision" : 2
}
Seeedstudio Moisture Sensor
- 2/5 voltage divider used (to get to 2v)
- single ended
"Moisture Sensor (Seeedstudio)" : {
"desc" : "Seeedstudio moisture sensor",
"conversion" : "xyz*50",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 5,
"rep_analog" : 1,
"default_tag" : "moisture",
"analog_tag" : "moisture",
"unit" : "%",
"precision" : 0
}
Seeedstudio Sound Sensor
- 2/5 voltage divider used (to get to 2v)
- single ended
"Sound Sensor (Seeedstudio)" : {
"desc" : "Seeedstudio sound sensor (arbitrary %)",
"conversion" : "xyz*50",
"analog" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 5,
"rep_analog" : 1,
"default_tag" : "sound",
"analog_tag" : "sound",
"unit" : "%",
"precision" : 0
},
Simple External Relay
To simply receive the state of an external relay, such as a video camera that opens and closes a relay based on whether it is recording, this template could be used:
"<You custom sensor name here>" : {
"desc" : "<You custom sensor description here>",
"digital" : true,
"rj45_v1" : true,
"tblock_v1" : true,
"do_volt0" : 24,
"rep_input0" : 1,
"input_tag0" : "<tag>",
"default_tag" : "<tag>",
"unit0" : "<closed unit>/<open unit>",
"inversion0": true
}