Power Measure

[中文]

This example demonstrates how to use the BL0937 power measurement chip to detect electrical parameters such as voltage, current, active power, and energy consumption.

Adapted Products

Name

Function

Vendor

Datasheet

HAL

BL0937

detect electrical parameters such as voltage, current, active power, and energy consumption

BELLING

BL0937 Datasheet

x

API Reference

The following API implements hardware abstraction for power measure. Users can directly call this layer of code to write sensor applications.

Header File

Functions

esp_err_t power_measure_init(power_measure_init_config_t *config)

power measure component int

Parameters

config – configuration for power measure hardware

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_NO_MEM

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_deinit()

power measure component deint

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t power_measure_get_voltage(float *voltage)

get current vltage (V)

Parameters

voltage – current voltage (V)

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_get_current(float *current)

get current current (A)

Parameters

current – current current (A)

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_get_active_power(float *active_power)

get current active power (W)

Parameters

active_power – current active power (W)

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_get_power_factor(float *power_factor)

get current power factor

Parameters

power_factor – power factor

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_get_energy(float *energy)

get current energy (Kw/h)

Parameters

energy – Power consumed by the load (Kw/h)

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_start_energy_calculation()

start the energy calculation

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_stop_energy_calculation()

stop the energy calculation

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_reset_energy_calculation()

reset the energy accumulated value in flash

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_start_calibration(calibration_parameter_t *para)

start calibration for factory test

Parameters

para – calibration parameters

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_get_calibration_factor(calibration_factor_t *factor)

get calibration factor from flash

Parameters

factor – calibration factor

Returns

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_INVALID_STATE

esp_err_t power_measure_calibration_factor_reset(void)

reset factor in flash

Returns

  • ESP_OK

  • ESP_FAIL POWER_MEASURE

Structures

struct overcurrent_event_data_t

Data structure for overcurrent event data.

Public Members

float current_value

Current value measured during the overcurrent event

uint16_t trigger_value

Trigger threshold for overcurrent detection

struct overvoltage_event_data_t

Data structure for overvoltage event data.

Public Members

float voltage_value

Voltage value measured during the overvoltage event

uint16_t overvalue

Threshold value for overvoltage detection

struct undervoltage_event_data_t

Data structure for undervoltage event data.

Public Members

float voltage_value

Voltage value measured during the undervoltage event

uint16_t undervalue

Threshold value for undervoltage detection

struct calibration_parameter_t

Structure for calibration parameters.

Public Members

float standard_power

Standard power in watts

float standard_voltage

Standard voltage in volts

float standard_current

Standard current in amperes

struct calibration_factor_t

Structure for calibration factors.

Public Members

float ki

Calibration factor for current

float ku

Calibration factor for voltage

float kp

Calibration factor for power

struct chip_config_t

Configuration structure for the chip.

Public Members

power_measure_chip_t type

Type of the chip used

calibration_factor_t factor

Calibration factors for the chip

gpio_num_t sel_gpio

GPIO number for selection

gpio_num_t cf1_gpio

GPIO number for CF1

gpio_num_t cf_gpio

GPIO number for CF

uint8_t pin_mode

Pin mode configuration

float sampling_resistor

Value of the sampling resistor

float divider_resistor

Value of the divider resistor

struct power_measure_init_config_t

Initialization configuration structure for power measurement.

Public Members

chip_config_t chip_config

Configuration for the chip

uint16_t overcurrent

Overcurrent threshold

uint16_t overvoltage

Overvoltage threshold

uint16_t undervoltage

Undervoltage threshold

bool enable_energy_detection

Flag to enable energy detection

Macros

STORGE_FACTOR_KEY

STORGE_FACTOR_KEY.

Enumerations

enum power_measure_event_t

POWER_MEASURE event base.

Enumeration of power measurement events.

Values:

enumerator POWER_MEASURE_INIT_DONE

Initialisation Done

enumerator POWER_MEASURE_OVERCURRENT

Overcurrent detected

enumerator POWER_MEASURE_OVERVOLTAGE

Overvoltage detected

enumerator POWER_MEASURE_UNDERVOLTAGE

Undervoltage

enumerator POWER_MEASURE_ENERGY_REPORT

report energy

enumerator POWER_MEASURE_HOME_APPLIANCES_ONLINE

appliances online

enumerator POWER_MEASURE_HOME_APPLIANCES_OFFLINE

appliances offline

enum power_measure_rated_voltage_t

Enumeration of rated voltage levels.

Values:

enumerator RATED_VOLTAGE_110V

Rated voltage of 110 volts

enumerator RATED_VOLTAGE_120V

Rated voltage of 120 volts

enumerator RATED_VOLTAGE_220V

Rated voltage of 220 volts

enum power_measure_chip_t

Enumeration of supported chip types.

Values:

enumerator CHIP_BL0937

BL0937 chip type

enumerator CHIP_MAX

Maximum chip type

Provide feedback about this document