Device Control API — npz_device_control.h / npz_device_control.c

High-level functions for configuring the nPZero device, reading sensor values after wake-up, handling ADC results, and controlling idle/reset states. Include npz_device_control.h in your application.

---

npz_device_configure

void npz_device_configure(npz_device_config_s *device_config);

Brief: Applies a complete device configuration to the nPZero G1S IC.

Description: Orchestrates the full configuration sequence in this order:

1. Global settings — timeout, SYSCFG1/2/3, power switch control, interrupt pin config.
2. Peripherals — for each non-NULL entry in device_config->peripherals[], writes CFGP, MODP, PERP, NCMDP, ADDRP, RREGP, THROVP, THRUNP, TWTP, TCFGP and uploads init bytes to SRAM.
3. Internal ADC — if adc_channels[0]->wakeup_enable == 1, writes THROVA1 and THRUNA1.
4. External ADC — if adc_channels[1]->wakeup_enable == 1 and adc_ext_sampling_enable == 1, writes THROVA2 and THRUNA2.

Any step failure prints a diagnostic message via printf and returns early without further configuration.

note

Call npz_hal_init() before this function. After this call, send the device to idle mode with npz_device_go_to_idle() to begin autonomous operation.

Parameters:

Name	Direction	Description
device_config	in	Pointer to a fully populated npz_device_config_s. Must not be NULL.

Returns: void. Check printf output or add custom error hooks for production use.

---

npz_device_go_to_idle

void npz_device_go_to_idle(void);

Brief: Commands the nPZero G1S IC to enter idle mode and assume autonomous control.

Description: Writes 0xFF to the IDLE_RST register (0x00). The IC shuts down the host power switch (SW_HP), takes control of the I²C bus, and begins autonomous peripheral management according to the previously applied configuration.

Call this after npz_device_configure() to enter the low power idle mode.

Parameters: None.

Returns: void.

Example:

npz_device_configure(&device_config);
npz_device_go_to_idle();
// Host will now be powered off

---

npz_device_soft_reset

void npz_device_soft_reset(void);

Brief: Performs a software reset of the nPZero G1S IC via I²C.

Description: Writes 0xA5 to the IDLE_RST register. The IC resets and enters Standby state, reverting all registers to power-on defaults. The host retains I²C bus control after reset.

After a soft reset, re-apply configuration with npz_device_configure() before calling npz_device_go_to_idle().

Parameters: None.

Returns: void.

---

npz_device_read_peripheral_value

bool npz_device_read_peripheral_value(npz_psw_e psw_lp, int index, int *peripheral_value);

Brief: Reads the last captured value from a peripheral after it triggered a wake-up.

Description: Reads the CFGP register of the given peripheral to determine its polling mode. If the mode involves threshold comparison (POLLING_MODE_PERIODIC_READ_COMPARE_THRESHOLD or POLLING_MODE_PERIODIC_WAIT_INTERRUPT_COMPARE_THRESHOLD), reads the VALP register and combines the two bytes (MSB from valp_h, LSB from valp_l) into peripheral_value. Works for both I²C and SPI peripherals.

Call this in the host wake-up handler when npz_register_sta2_s.perN_triggered is set.

Parameters:

Name	Direction	Description
psw_lp	in	Low-power switch ID for the peripheral (PSW_LP1–PSW_LP4).
index	in	Peripheral index (0–3), used for diagnostic messages.
peripheral_value	out	Pointer to an int that receives the 16-bit peripheral reading.

Returns: true on success, false if any register read fails.

Example:

npz_register_sta2_s sta2 = {0};
npz_read_STA2(&sta2);

if (sta2.per1_triggered) {
    int value = 0;
    if (npz_device_read_peripheral_value(PSW_LP1, 0, &value)) {
        // value holds the last sensor reading
    }
}

---

npz_device_handle_adc_internal

bool npz_device_handle_adc_internal(void);

Brief: Reads and decodes the internal ADC (VBAT) value after a triggered wake-up.

Description: Reads the ADC_CORE register and maps the 5-bit code to a millivolt value using an internal lookup table covering 1.5 V to 3.6 V. Prints the result via printf.

Call this in the wake-up handler when npz_register_sta1_s.int_adc_triggered is set.

VBAT Code-to-Voltage Map:

Code	Voltage	Code	Voltage
0x04	1.5 V	0x10	2.6 V
0x06	1.6 V	0x11	2.7 V
0x08	1.7 V	0x11	2.8 V
0x09	1.8 V	0x12	2.9 V
0x0A	1.9 V	0x12	3.0 V
0x0B	2.0 V	0x13	3.1 V
0x0C	2.1 V	0x13	3.2 V
0x0D	2.2 V	0x13	3.3 V
0x0E	2.3 V	0x14	3.4 V
0x0F	2.4 V	0x14	3.5 V
0x0F	2.5 V	0x14	3.6 V

Parameters: None.

Returns: true on success, false if the register read fails or the code is not in the map.

---

npz_device_handle_adc_external

bool npz_device_handle_adc_external(void);

Brief: Reads and decodes the external ADC (ADC_IN) value after a triggered wake-up.

Description: First verifies that external ADC is enabled in SYSCFG1 and SYSCFG2. Reads the ADC_EXT register and maps the 6-bit code to a millivolt value.

Call this in the wake-up handler when npz_register_sta1_s.ext_adc_triggered is set.

ADC_IN Code-to-Voltage Map:

Code	Voltage	Code	Voltage	Code	Voltage
0x00	0.6 V	0x26	1.6 V	0x30	2.6 V
0x08	0.7 V	0x28	1.7 V	0x31	2.7 V
0x0F	0.8 V	0x29	1.8 V	0x31	2.8 V
0x15	0.9 V	0x2A	1.9 V	0x32	2.9 V
0x19	1.0 V	0x2B	2.0 V	0x32	3.0 V
0x1C	1.1 V	0x2C	2.1 V	0x33	3.1 V
0x1F	1.2 V	0x2D	2.2 V	0x33	3.2 V
0x22	1.3 V	0x2E	2.3 V	0x33	3.3 V
0x23	1.4 V	0x2F	2.4 V	0x34	3.4 V
0x24	1.5 V	0x2F	2.5 V	0x34	3.6 V

Parameters: None.

Returns: true on success, false on register read failure or unrecognized code.