Skip to main content

hardware.vbat()

Returns the true battery voltage of devices based on certain imps

Availability

Device

Returns

Float — the actual battery voltage (VBAT)

Description

Compare this method with hardware.voltage() which yields the voltage as measured at the imp’s power terminals. Rechargeable batteries contain circuitry to maintain a consistent output voltage for as long as possible while the battery drains. However, the voltage ahead of this circuitry falls as the battery’s charge depletes. The imp003 has a VBAT pin by which this cell voltage can be measured.

Developers can use hardware.vbat() to monitor the cell voltage, the better to track battery life. Because hardware.voltage() presents the battery’s modulated output, this API method may not give sufficient warning before the output voltage suddenly drops — potentially below the imp’s expected 3.3V — as the battery empties.

This method will only yield a result when called by code running on an imp003 (Murata LBWA1ZV1CD), imp004m (Murata LBEE5ZZ1MD) or impC001. If it is called by code running on an imp001, imp002 or imp005, it will generate an error message: ERROR: the index 'vbat' does not exist.