SEARCH: i2c

Adding 2-wire (I2C) environmental sensor

To add a 2-wire (I2C) temperature or environmental sensor, you should select any pin, select the “Temperature (2-wire)” sensor type, and select a subtype (e.g., BMx280), specify the I2C address of the sensor as a decimal number. On the next row (Output2 in this example), you should define a I2C clock pin.

Adding 2-wire (I2C) environmental sensor
Adding 2-wire (I2C) environmental sensor

I2C sensors

First of all, you must specify a pin for a sensor. It is the SDA pin. Then it would help if you defined the SCL pin. For example, output 4 – BME280, and output 5 – I2C SCL.

I2C configuration for a sensor

If you connect several sensors on one bus (pin), you may define the SCL pin only once.

I2C configuration for sensors on one bus

Zigbee: Accepts the “read” and “write” commands on the endpoint for the SDA pin.

Current and voltage monitoring (INA219, INA226, INA3221)

The INA226 is a high-side current shunt and power monitor with an I2C interface. These sensors offer high accuracy for current and voltage measurements in various applications. With its integrated ADC, the INA226 can measure bus voltages from 0V to 36V and shunt voltages with a common-mode voltage range. It provides programmable conversion times and averaging, making it versatile for different precision requirements.

The INA219 is a simpler device suitable for basic current sensing applications, while the INA226 offers higher precision and additional features such as integrated voltage reference and programmable alert functions. The INA226 is ideal for more demanding applications that require precise current measurement and advanced monitoring capabilities.

INA3221 offers a 3-channel monitoring module.

INA sensors are I2C-compatible and commonly used in power management systems, battery chargers, and various industrial applications where accurate current and voltage measurements are essential for monitoring and control purposes.

INA sensor configuration example
INA sensor configuration example

INA219 resolution – this option allows you to select a measurement voltage and current range (wider range – less accuracy).

INA226 resolution – this option depends on a used shunt resistor with your sensor or sensor board (less current – higher accuracy). Please note that the firmware does not support other nominal values for shunt resistors.

X9C100 digital potentiometer and Zigbee

The X9C102, X9C103, X9C104, X9C503 are digitally controlled (XDCP) potentiometers. The device consists of a resistor array, wiper switches, a control section, and nonvolatile memory. The wiper position is controlled by a three-wire interface.

⚠️ THIS FEATURE IS AVAILABLE ON CC2652 or CC1352 CHIPS ONLY

X9C103S - digital potentiometer
X9C103S – digital potentiometer

Connecting X9C10X to a Zigbee module

From X9C10X to a Zigbee module:
GND: connected to GND on a Zigbee module.
CS (chip select): Connected to any pin configured as X9C100 (P00 – DIO0, see below).
INC (increment): Connected to any pin configured as I2C SCL/SPI CLK (e.g., P02 – DIO2).
U/D (up/down): : Connected to any pin configured as an additional parameter (e.g., P04 – DIO4).
VCC: Connected to 3.3V.

Firmware configuration

Firmware configuration

Remember state – if this option is active, the firmware remembers the last level and restores it after power up. Otherwise, the firmware sets the maximum resistance on the X9C10X output (VL – VW).
Pin (Up/Down) – it is the “U/D” pin. It has the same pull-up resistor settings as the master output pin.
Transition time (ms) – if this interval is not zero, the firmware smoothly changes the output resistance between two states.
Linked input – the mode of the linked input that controls this output.

Zigbee commands

The device acts as a level control device. You can change the level from 0 to 255, and the firmware scales it to 0 – 99 levels in X9C10X. When you set the zero level in Zigbee, the firmware forcibly makes 99 steps down. It allows synchronizing levels between the device and Zigbee. In other cases, the firmware calculates a difference and makes the necessary number of steps up or down.

Zigbee cluster: ZCL_CLUSTER_ID_GEN_LEVEL_CONTROL
Zigbee attributes: ATTRID_LEVEL_CURRENT_LEVEL (uint8)
Zigbee commands: read, write, moveToLevel, moveToLevelWithOff

Zigbee2MQTT commands

on/off - The "Off" command sets the minimum level, and the "On" command restores the last level (before off). Look for commands and examples for GPIO outputs.
write - sets the level.
Topic: zigbee2mqtt/[friedly_name]/[channel]/set/brightness
Channel: l1, l2, l3 … l16
Payload: value (0 - 255)
Topic: zigbee2mqtt/[friedly_name]/set/[channel]
Channel: l1, l2, l3 … l16
Payload: {"brightness": value, "transition": 3}
value - 0 - 255.
transition - (optional) the transition time in seconds between states.
read - reads the current value
Topic: zigbee2mqtt/[friedly_name]/[channel]/get/brightness
Payload: none
Returns: {"brightness_[channel]": value}

HX711 weight sensor and Zigbee

The HX711 Load Cell Amplifier is a module that is used to take the signal coming from your load cell and convert it into a digital signal that your Zigbee-compatible chip can take and process.

⚠️ THIS FEATURE IS AVAILABLE ON CC2652 or CC1352 CHIPS ONLY

Connecting HX711 and Load Cell to a Zigbee module

From Load Cell to HX711:
Red wire: E+ on HX711
White wire: A-
Black wire: E-
Green wire: A+

HX711 Load Cell
Load Cell
HX711 module

From HX711 to a Zigbee module:
GND: connected to GND on a Zigbee module.
DT (data): Connected to any pin configured as HX711 (P00 – DIO0, see below).
SCK: Connected to any pin configured as I2C SCL/SPI CLK (e.g., P02 – DIO2).
VCC: Connected to 3.3V.

Firmware configuration

Zigbee’s firmware settings

Scale factor – allows you to convert a raw sensor’s value to a weight value.

Shift – allows you to calibrate a zero offset (tare weight).

Calibration

  1. Assemble your Zigbee device (connect a load cell, power, etc.).
  2. Configure and upload the firmware with “Scale factor” = 1.0 and “Shift” = 0.
  3. Save a custom converter for your device (on the Experts tab) and add it to your Z2M.
  4. Join your device to your Zigbee network.
  5. Remove any weight from your load cell.
  6. You should start receiving raw measurement data. It is the shift value (tare weight). Write it down somewhere. Then you can enable the “Enable zero calibration” switch in Z2M, and the device will remember this value in NVRAM.
  7. Place any known weight on your load cell (you can find several tutorials about this on Google).
  8. You should receive a new raw value for the measured weight.
  9. Calculate a scale factor: (Measured value – Zero value) / Weight (kilograms or pounds).
  10. Type the scale factor in the corresponding field in Z2M and press Enter. The device will remember this value in NVRAM.
  11. Finally, you can update these constants in the firmware and re-flash it. In this case, you do need to make a new calibration when you reset a device to the factory defaults.

Zigbee commands

Zigbee cluster: ZCL_CLUSTER_ID_GEN_ANALOG_INPUT_BASIC
Zigbee attributes: ATTRID_IOV_BASIC_PRESENT_VALUE (single precision float)
Zigbee commands: write

Zigbee2MQTT commands

on/off - Enables the zero calibration process (tare). Look for commands and examples for GPIO outputs.
write - sets the PWM duty cycle.
Topic: zigbee2mqtt/[friedly_name]/[channel]/set/brightness
Channel: l1, l2, l3 … l16
Payload: value (1-99999999, scale factor)

SDC40/41 CO2 sensor

This sensor measures environmental temperature, humidity and CO2 level. It I2C- compatible sensor where you should configure the SDA and SCL pins, and define the sensor I2C address (see an example below). Of course, you can any other pins in your setup.

If your device is configured for power saving, the sensor measures all values only once when the firmware sends a periodic report. Please note, that every measurement takes about 6 seconds.

Otherwise, the sensor measures all values periodically every 5 seconds, but the firmware sends measured values with periodic reports.

⚠️ THIS FEATURE IS AVAILABLE ON CC2652 or CC1352 CHIPS ONLY

SCD40/41 configuration example
SCD40/41 configuration example

Additional parameters

Altitude – altitude over a sea level of your location for precise results.

Auto-calibration – the sensor will self-calibrate every several hours if you enabled this option.

Zigbee commands

You may send some sensor-specific commands to your higher-level system. You should write the necessary command single precision value to the “Analog input” cluster.

63000 – factory reset.
63001 – sensor restart (re-init).
63002 – start self testing. It takes about 10 seconds.
63900 – 64100 – set a temperature offset (64000 + offset value, so, the offset can be positive or negative). By default, the sensor has the temperature offset of 4°C. If you see that the sensor measures a wrong temperature value, you can change this offset.
65000 – 66100 – set the ambient pressure in kPa (65000 + pressure value). The maximum pressure value is 1100 kPa.

write - Zigbee write command.
Topic: zigbee2mqtt/[friedly_name]/set
Payload: {"[channel]": 63002}
Channel: l1, l2, l3 … l16

Real-time clock (DS3231 or DS1307 RTC)

The firmware supports the most popular RTC chips like DS3231 and DS1307. These battery-powered chips can count time independently with the main module. The firmware reads the time from these chips at the boot time and periodically synchronizes the module’s time with RTC.

RTC chips support the I2C protocol. Therefore, you can add them in a similar way, like other I2C sensors.

⚠️ THIS FEATURE IS AVAILABLE IN THE PREMIUM VERSION

⚠️ THIS FEATURE IS NOT AVAILABLE IN THE CC2530/CC2531 ROUTER FIRMWARE

RTC clock setup

Zigbee internals

Zigbee cluster: ZCL_CLUSTER_ID_GEN_TIME
Zigbee attributes: ATTRID_TIME_TIME (UTC data type, 32-bit number of seconds since Jan 1, 2000)
Zigbee commands: read, write.

Zigbee2MQTT commands

You should create a custom converter for your device, place it in the “data” folder, and add it to the configuration.

read - immediately reads the current time.
Topic: zigbee2mqtt/[friedly_name]/get/[channel]
Channel: l1, l2, l3 … l16
Payload: 1
Returns: The counter value {"[channel]": float_value}
write - this command allows you to synchronize time with the host. It is not recommended to call it directly because the device expects an encoded value. The custom converter gets the current host's time and calculates the correct value automatically.
Command example:
const values = {timeStatus: 3, time: time};
endpoint.write('genTime', values);

Rotary encoder

A rotary encoder is a type of position sensor used to determine the angular position of a rotating shaft. It generates an electrical signal, either analog or digital, according to the rotational movement (more info).

Digital rotary encoder
Digital rotary encoder

The firmware counts impulses in the 500 ms interval and sends a positive value for CW rotations and a negative value for CCW rotations. Optionally, the firmware can handle and send an event for a click button.

Wiring

Output 2 → S1
Output 3 → S2
Input 1 → Key
GND → GND
3.3V → VCC

Firmware configuration

Firmware configuration for rotary encoder

The image above is an example. You can connect “Output 1” and “Output 2” signals to any available pins. The “I2C SCL” line should be defined immediately after the “Rotary encoder” sensor.

Note: Output and input pins are not relevant for sensors. You can also configure your rotary in input pins, but without additional options.

Changes level – this option allows you to link the rotary encoder to a PWM or LED output and control PWM signal width or brightness level up or down.

Sensitivity – this option is used when with the previous option and changes a step size per each tick.

If your encoder has the additional push button, you can connect it to an input, and it will toggle a linked output state.

Ultrasonic sensors (US100, HC-SR04 or similar)

These ultrasonic sonar distance sensors are really common in robotics projects, but they can also be used for automation, interactive art, and motion sensing. They work at about 2 cm to 450 cm away, but we think 10 cm – 250 cm will get you the best results. Sensors look very similar and have a pair of flippers.

⚠️ THIS FEATURE IS NOT AVAILABLE IN THE CC2530/CC2531 ROUTER FIRMWARE

US-100 ultrasonic sensor

The US-100 is very similar to the popular HC-SR04 ultrasonic sensor and even looks the same, but it can work in the UART mode and provide more precise measurements. Compatible sensors are (there are many clones, but you can find examples of data packets below):

HY-SRF05, HC-SR04, HC-SR04 3-5V, US-100, HC-SR04P, US-015, US-016, HC-SR04+, US-026, IOE-SR05, RCWL-1601, AJ-SR04M:

These sensors return two bytes with a distance values:
0x12 0x34 (MSB LSB)
MSB – most significant byte.
LSB – less significant byte.

HRLV-MaxSonar series:

The sensor returns a value as ASCII characters:
R1234<CR>
<CR> – ASCII code 0x0D

JSN-sr04t, DYP-A01, A02YYUW:

These sensors return two bytes with a distance values:
0xFF MSB LSB CRC
0xFF – fixed header byte.
CRC – Checksum as a sum of all bytes before.

DFRobot URM06, URM07:

These sensors return two bytes with a distance values:
0x55 0xAA 0x11 0x02 0x02 MSB LSB CRC
0x55 0xAA – fixed header byte.
CRC – Checksum as a sum of all bytes before.

Zigbee firmware configuration for US100

It would be best if you used the jumper is on the board to select the UART mode.

The firmware configuration for US100

Connections

P02 (UART RX) → Tx
P03 (UART TX) → Rx
GND → GND
3.3V → VCC
Do not forget about the jumper. If you do not receive data from this sensor, try to swap Rx and Tx wires.

Zigbee firmware configuration for HC-SR04 compatible sensors

This sensor requires a trigger signal to start a measurement, and the firmware uses the “I2C SCL” signal for it. It would be best if you defined it immediately after the HC-SR04 sensor.

Note: the firmware cannot measure a signal width with precision in microseconds. Therefore, the measured distance is rounded to about 15 centimeters. If you need better accuracy, use US100 instead.

The firmware configuration for HC-SR04

Connections

I2C SCL → Trig
HC-SR04 → Echo
GND → GND
3.3V → VCC

Interval

If the value in the “Interval” field is not zero, the firmware executes measurement every N seconds. It sends a new value to a coordinator only if a distance value changes. But the firmware always sends the latest measured value with a periodic report.

16-channel Zigbee PWM controller (PCA9685)

The PCA9685 is an I2C-bus controlled 16-channel LED controller optimized for Red/Green/Blue/Amber (RGBA) color backlighting applications. Each LED output has its own 12-bit resolution (4096 steps) fixed frequency individual PWM controller that operates at a programmable frequency from a typical of 24 Hz to 1526 Hz with a duty cycle that is adjustable from 0% to 100 % to allow the LED to be set to a specific brightness value. All outputs are set to the same PWM frequency.

PCA9685. Typical configuration
Fig. 1. PCA9685. Typical configuration

The configuration above is for 8 channels on a controller connected to P15 (SDA) and P13 (SCL) pins.

Address – it is the I2C address. The default value is 0x70 (hex) or 112 (dec).

Inversed – if this option is enabled and the PWM channel is off, the output will have the HIGH level. Otherwise, the output will change the LOW level.

Frequency – PWM frequency. The firmware uses a value from the first defined channel (in this example, Output 1).

Channel – PWM channel number from 0 to 15.

Type – the PWM output type (fig. 2).

PWM output type
Fig. 2. PWM output type

Zigbee2MQTT commands

on/off - Look for commands and examples for GPIO outputs.
write - sets the PWM duty cycle.
Topic: zigbee2mqtt/[friedly_name]/[channel]/set/brightness
Channel: l1, l2, l3 … l16
Payload: value (0..254)
Topic: zigbee2mqtt/[friedly_name]/set/[channel]
Channel: l1, l2, l3 … l16
Payload: {"brightness": value, "transition": 3}
value: 0 .. 254.
transition: (optional) the transition time in seconds between states.
read - reads the current value
Topic: zigbee2mqtt/[friedly_name]/[channel]/get/brightness
Payload: none
Returns: {"brightness_[channel]": value}