Add ESP Upload Component workflow and Update documentation

.github/workflows/esp_upload_component.yml

@@ -0,0 +1,20 @@
+name: Upload component to Espressif Component Service
+
+# If the commit is tagged, it will be uploaded. Other scenario silently fail.
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  upload_components:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Upload component to component registry
+        uses: espressif/upload-components-ci-action@v1
+        with:
+          namespace: "zivlow"
+          name: "ina226"
+          version: ${{ github.ref_name }}
+          api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}

README.md

@@ -1,22 +1,46 @@
 # INA226 component for ESP-IDF
 
+[![Component Registry](https://components.espressif.com/components/zivlow/ina226/badge.svg)](https://components.espressif.com/components/zivlow/ina226) [![Example build](https://github.com/zivlow/ina226/actions/workflows/build_example.yml/badge.svg)](https://github.com/zivlow/ina226/actions/workflows/build_example.yml)
+
 This library is an ESP-IDF component for the INA226 power monitor IC.
 
 ## Using component
-```
+```bash
 idf.py add-dependency "zivlow/ina226"
 ```
 
 ## Example
-```
+```bash
 idf.py create-project-from-example "zivlow/ina226:ina226-example"
 ```
 
-```
+```bash
 cd ina226-example
 idf.py flash monitor
 ```
 
+## I2C pins
+If using ESP32 DevKitC, the default I2C pins has been set to GPIO 21 (SDA) and GPIO 22 (SCL).
+```cpp
+// Use default I2C pins GPIO 21 (SDA) and GPIO 22 (SCL)
+INA226 CurrentSensor;
+```
+
+If using other ESP32 product variants (e.g. ESP32s3), or if you want to select custom I2C pins, put your desired I2C pins as parameter arguments.
+```cpp
+// Custom I2C pins
+INA226 CurrentSensor{SDA_GPIO_NUM, SCL_GPIO_NUM};
+```
+
+## INA226 address
+The default constructor will use default I2C address `0x40`.
+
+To set a different I2C address, add the desired address as the third parameter.
+```cpp
+// Custom INA226 address
+INA226 CurrentSensor{SDA_GPIO_NUM, SCL_GPIO_NUM, INA226_CUSTOM_ADDRESS};
+```
+
 ## API
 Refer to [Documentation](https://zivlow.github.io/ina226/html/index.html).
 

docs/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 794f1e4d9437ed673ee1344de9c3171e
+config: 87e24e6f3e75349b8c7d9c0cde65de23
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/genindex.html

@@ -78,7 +78,7 @@ <h2 id="I">I</h2>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="index.html#_CPPv46INA226">INA226 (C++ class)</a>
 </li>
-      <li><a href="index.html#_CPPv4N6INA2268I2C_InitE10gpio_num_t10gpio_num_t8uint16_t">INA226::I2C_Init (C++ function)</a>
+      <li><a href="index.html#_CPPv4N6INA2266INA226EK10gpio_num_tK10gpio_num_tK8uint16_tK8uint32_tK14i2c_port_num_t">INA226::INA226 (C++ function)</a>
 </li>
       <li><a href="index.html#_CPPv413INA226_Driver">INA226_Driver (C++ class)</a>
 </li>
@@ -208,7 +208,7 @@ <h2 id="I">I</h2>
 </li>
       <li><a href="index.html#_CPPv4N13INA226_Driver29GetShuntVoltageConversionTimeEv">INA226_Driver::GetShuntVoltageConversionTime (C++ function)</a>
 </li>
-      <li><a href="index.html#_CPPv4N13INA226_Driver4InitEK8uint32_tK8uint32_t">INA226_Driver::Init (C++ function)</a>
+      <li><a href="index.html#_CPPv4N13INA226_Driver10InitDriverEK8uint32_tK8uint32_t">INA226_Driver::InitDriver (C++ function)</a>
 </li>
       <li><a href="index.html#_CPPv4N13INA226_Driver13OperatingModeE">INA226_Driver::OperatingMode (C++ enum)</a>
 </li>

docs/html/index.html

@@ -48,7 +48,7 @@
 <li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
 <li><a class="reference internal" href="#api">API</a><ul>
 <li><a class="reference internal" href="#_CPPv46INA226"><code class="docutils literal notranslate"><span class="pre">INA226</span></code></a><ul>
-<li><a class="reference internal" href="#_CPPv4N6INA2268I2C_InitE10gpio_num_t10gpio_num_t8uint16_t"><code class="docutils literal notranslate"><span class="pre">INA226::I2C_Init()</span></code></a></li>
+<li><a class="reference internal" href="#_CPPv4N6INA2266INA226EK10gpio_num_tK10gpio_num_tK8uint16_tK8uint32_tK14i2c_port_num_t"><code class="docutils literal notranslate"><span class="pre">INA226::INA226()</span></code></a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#_CPPv413INA226_Driver"><code class="docutils literal notranslate"><span class="pre">INA226_Driver</span></code></a><ul>
@@ -158,7 +158,7 @@
 <li><a class="reference internal" href="#_CPPv4N13INA226_Driver16AlertTriggerMask5ERRORE"><code class="docutils literal notranslate"><span class="pre">INA226_Driver::AlertTriggerMask::ERROR</span></code></a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#_CPPv4N13INA226_Driver4InitEK8uint32_tK8uint32_t"><code class="docutils literal notranslate"><span class="pre">INA226_Driver::Init()</span></code></a></li>
+<li><a class="reference internal" href="#_CPPv4N13INA226_Driver10InitDriverEK8uint32_tK8uint32_t"><code class="docutils literal notranslate"><span class="pre">INA226_Driver::InitDriver()</span></code></a></li>
 </ul>
 </li>
 </ul>
@@ -214,20 +214,19 @@ <h1>API<a class="headerlink" href="#api" title="Link to this heading"></a></h
 <div class="breathe-sectiondef docutils container">
 <p class="breathe-sectiondef-title rubric" id="breathe-section-title-public-functions">Public Functions</p>
 <dl class="cpp function">
-<dt class="sig sig-object cpp" id="_CPPv4N6INA2268I2C_InitE10gpio_num_t10gpio_num_t8uint16_t">
-<span id="_CPPv3N6INA2268I2C_InitE10gpio_num_t10gpio_num_t8uint16_t"></span><span id="_CPPv2N6INA2268I2C_InitE10gpio_num_t10gpio_num_t8uint16_t"></span><span id="INA226::I2C_Init__gpio_num_t.gpio_num_t.uint16_t"></span><span class="target" id="classINA226_1a23bcd7c1bd459fa2c70190cb792b11ec"></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">expected</span></span><span class="p"><span class="pre">&lt;</span></span><span class="kt"><span class="pre">void</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">runtime_error</span></span><span class="p"><span class="pre">&gt;</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">I2C_Init</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">gpio_num_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">sda_io_num</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">GPIO_NUM_21</span></span>, <span class="n"><span class="pre">gpio_num_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">scl_io_num</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">GPIO_NUM_22</span></span>, <span class="n"><span class="pre">uint16_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">address</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">DEFAULT_INA226_I2C_ADDRESS</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N6INA2268I2C_InitE10gpio_num_t10gpio_num_t8uint16_t" title="Link to this definition"></a><br /></dt>
+<dt class="sig sig-object cpp" id="_CPPv4N6INA2266INA226EK10gpio_num_tK10gpio_num_tK8uint16_tK8uint32_tK14i2c_port_num_t">
+<span id="_CPPv3N6INA2266INA226EK10gpio_num_tK10gpio_num_tK8uint16_tK8uint32_tK14i2c_port_num_t"></span><span id="_CPPv2N6INA2266INA226EK10gpio_num_tK10gpio_num_tK8uint16_tK8uint32_tK14i2c_port_num_t"></span><span id="INA226::INA226__gpio_num_tC.gpio_num_tC.uint16_tC.uint32_tC.i2c_port_num_tC"></span><span class="target" id="classINA226_1a4b6c5c97a540af14fb40fc3591b1fc58"></span><span class="sig-name descname"><span class="n"><span class="pre">INA226</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">gpio_num_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">sda_io_num</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="k"><span class="pre">static_cast</span></span><span class="p"><span class="pre">&lt;</span></span><span class="n"><span class="pre">gpio_num_t</span></span><span class="p"><span class="pre">&gt;</span></span><span class="p"><span class="pre">(</span></span><span class="n"><span class="pre">CONFIG_I2C_MASTER_SDA</span></span><span class="p"><span class="pre">)</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">gpio_num_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">scl_io_num</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="k"><span class="pre">static_cast</span></span><span class="p"><span class="pre">&lt;</span></span><span class="n"><span class="pre">gpio_num_t</span></span><span class="p"><span class="pre">&gt;</span></span><span class="p"><span class="pre">(</span></span><span class="n"><span class="pre">CONFIG_I2C_MASTER_SCL</span></span><span class="p"><span class="pre">)</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint16_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">address</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">CONFIG_INA226_I2C_ADDRESS</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint32_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">scl_frequency</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">CONFIG_I2C_MASTER_FREQUENCY</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">i2c_port_num_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">i2c_port_num</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="k"><span class="pre">static_cast</span></span><span class="p"><span class="pre">&lt;</span></span><span class="n"><span class="pre">i2c_port_num_t</span></span><span class="p"><span class="pre">&gt;</span></span><span class="p"><span class="pre">(</span></span><span class="n"><span class="pre">CONFIG_I2C_MASTER_PORT_NUM</span></span><span class="p"><span class="pre">)</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N6INA2266INA226EK10gpio_num_tK10gpio_num_tK8uint16_tK8uint32_tK14i2c_port_num_t" title="Link to this definition"></a><br /></dt>
 <dd><p>Initializes the I2C of ESP-IDF. </p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
-<li><p><strong>sda_io_num</strong> – <strong>[in]</strong> GPIO number of SDA pin </p></li>
-<li><p><strong>scl_io_num</strong> – <strong>[in]</strong> GPIO number of SCL pin </p></li>
-<li><p><strong>address</strong> – <strong>[in]</strong> I2C address of <a class="reference internal" href="#classINA226"><span class="std std-ref">INA226</span></a></p></li>
+<li><p><strong>sda_io_num</strong> – <strong>[in]</strong> GPIO number of SDA pin. Defaults to GPIO 21 for ESP32. </p></li>
+<li><p><strong>scl_io_num</strong> – <strong>[in]</strong> GPIO number of SCL pin. Defaults to GPIO 22 for ESP32. </p></li>
+<li><p><strong>address</strong> – <strong>[in]</strong> I2C address of <a class="reference internal" href="#classINA226"><span class="std std-ref">INA226</span></a>. Defaults to 0x40. </p></li>
+<li><p><strong>scl_frequency</strong> – <strong>[in]</strong> Frequency of SCL pin. Defaults to 100000. </p></li>
+<li><p><strong>i2c_port_num</strong> – <strong>[in]</strong> I2C port number. </p></li>
 </ul>
 </dd>
-<dt class="field-even">Returns<span class="colon">:</span></dt>
-<dd class="field-even"><p>std::expected&lt;void, std::runtime_error&gt; </p>
-</dd>
 </dl>
 </dd></dl>
 
@@ -909,8 +908,8 @@ <h1>API<a class="headerlink" href="#api" title="Link to this heading"></a></h
 <div class="breathe-sectiondef docutils container">
 <p class="breathe-sectiondef-title rubric" id="breathe-section-title-public-functions">Public Functions</p>
 <dl class="cpp function">
-<dt class="sig sig-object cpp" id="_CPPv4N13INA226_Driver4InitEK8uint32_tK8uint32_t">
-<span id="_CPPv3N13INA226_Driver4InitEK8uint32_tK8uint32_t"></span><span id="_CPPv2N13INA226_Driver4InitEK8uint32_tK8uint32_t"></span><span id="INA226_Driver::Init__uint32_tC.uint32_tC"></span><span class="target" id="classINA226__Driver_1a08ff76529dfe2a8d546b649419121c2f"></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">expected</span></span><span class="p"><span class="pre">&lt;</span></span><span class="kt"><span class="pre">void</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">runtime_error</span></span><span class="p"><span class="pre">&gt;</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Init</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint32_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">ShuntResistor_mOhm</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="m"><span class="pre">100</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint32_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">MaxCurrent_A</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="m"><span class="pre">1</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N13INA226_Driver4InitEK8uint32_tK8uint32_t" title="Link to this definition"></a><br /></dt>
+<dt class="sig sig-object cpp" id="_CPPv4N13INA226_Driver10InitDriverEK8uint32_tK8uint32_t">
+<span id="_CPPv3N13INA226_Driver10InitDriverEK8uint32_tK8uint32_t"></span><span id="_CPPv2N13INA226_Driver10InitDriverEK8uint32_tK8uint32_t"></span><span id="INA226_Driver::InitDriver__uint32_tC.uint32_tC"></span><span class="target" id="classINA226__Driver_1a9f2cc4f2b30234b28e2f8ee09cfe81cb"></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">expected</span></span><span class="p"><span class="pre">&lt;</span></span><span class="kt"><span class="pre">void</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">runtime_error</span></span><span class="p"><span class="pre">&gt;</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">InitDriver</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint32_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">ShuntResistor_mOhm</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">CONFIG_INA226_SHUNT_RESISTOR_MILLIOHMS</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint32_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">MaxCurrent_A</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="n"><span class="pre">CONFIG_INA226_MAX_CURRENT_AMPS</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N13INA226_Driver10InitDriverEK8uint32_tK8uint32_t" title="Link to this definition"></a><br /></dt>
 <dd><p>Initializes the <a class="reference internal" href="#classINA226"><span class="std std-ref">INA226</span></a> driver. </p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>