Merge pull request #2 from arduino-libraries/improvements

Clean up for release

Author: sebromero

Diff for: .github/workflows/check-arduino.yml renamed to .github/workflows/arduino-lint.yml

@@ -1,4 +1,4 @@
-name: Check Arduino
+name: Arduino Linter
 
 # See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows
 on:

Diff for: .github/workflows/compile-examples.yml

@@ -22,9 +22,8 @@ on:
 
 env:
   UNIVERSAL_SKETCH_PATHS: |
-        - examples/WakeFromGPIO
+        - examples/WakeFromPin
         - examples/WakeFromRTC
-        - examples/TurnPeripheralsOff
   SKETCHES_REPORTS_PATH: sketches-reports
   SKETCHES_REPORTS_ARTIFACT_NAME: sketches-reports
 

Diff for: .github/workflows/render-documentation.yml

@@ -2,11 +2,15 @@ name: Render Documentation
 
 on:
   push:
+    branches:
+      - main
     paths:
       - ".github/workflows/render-documentation.ya?ml"
       - "examples/**"
       - "src/**"
   pull_request:
+    branches:
+      - main
     paths:
       - ".github/workflows/render-documentation.ya?ml"
       - "examples/**"
@@ -15,13 +19,10 @@ on:
 
 jobs:
   render-docs:
-    runs-on: ubuntu-latest
     permissions:
       contents: write
-
-    steps:
-    - uses: actions/checkout@v4
-    - uses: sebromero/render-docs-github-action@main
-      with:
-        source-path: './src'
-        target-path: './docs/api.md'
+    uses: arduino/render-docs-github-action/.github/workflows/render-docs.yml@main
+    with:
+      source-path: './src'
+      target-path: './docs/api.md'
+      commit: ${{ github.event_name != 'pull_request' }} # Only commit changes if not a PR

Diff for: README.md

@@ -5,20 +5,20 @@
 The Portenta C33 Low Power Library is a library designed to optimize power consumption for projects using the Portenta C33 boards, which are powered by the Renesas RA6M5 microcontroller. The library achieves this by providing access to various low power modes. These modes are essential for applications where power efficiency is crucial, such as in remote sensing, IoT devices, or battery-powered applications.
 
 ## Examples 
-* [WakeFromGPIO](https://github.com/arduino-libraries/Arduino_LowPowerPortentaC33/blob/main/examples/WakeFromGPIO/WakeFromGPIO.ino) - This example demonstrates how you can use [the GPIO pins](https://github.com/arduino-libraries/Arduino_LowPowerPortentaC33/blob/main/docs/README.md#wakeup-pins) to wake your board from sleep.
-* [WakeFromRTC](https://github.com/arduino-libraries/Arduino_LowPowerPortentaC33/blob/main/examples/WakeFromRTC/WakeFromRTC.ino) - This example demonstrates how you can use the RTC to wake the board from sleep. 
+* [WakeFromPin](./examples/WakeFromPin/WakeFromPin.ino) - This example demonstrates how you can use [the GPIO pins](#wake-up-pins) to wake your board from sleep.
+* [WakeFromRTC](./examples/WakeFromRTC/WakeFromRTC.ino) - This example demonstrates how you can use the RTC to wake the board from sleep. 
 
-## 😴 Sleep Modes
+## 💤 Sleep Modes
 
-### Sleep 
+### 🥱 Sleep 
 * **Function**: Reduces the microcontroller's power usage to about half of its normal consumption.
 * **Effect**: Upon waking up from this mode, the execution of your program resumes exactly where it stopped. This is particularly useful for applications that require a quick resume with minimal power savings.
 * **Wake-Up Triggers**: The board can be configured to wake up either from an RTC alarm or an external interrupt pin.
 
-### Deep Sleep
-* **Function**: Significantly reduces power usage to approximately 100uA (when all peripherals are off), making it ideal for long-term, battery-dependent operations.
-* **Effect**: Unlike Sleep Mode, waking up from Deep Sleep Mode restarts the board, triggering the void setup() function. This behavior is suitable for scenarios where a full reset is acceptable or desired upon waking up.
-* **Wake-Up Triggers**: The board can be configured to wake up either from an RTC alarm or an external interrupt pin.
+### 😴 Deep Sleep
+- **Function**: Significantly reduces power usage to approximately 100uA (when all peripherals are off), making it ideal for long-term, battery-dependent operations.
+- **Effect**: Unlike Sleep Mode, waking up from Deep Sleep Mode restarts the board, triggering the `setup()` function. This behavior is suitable for scenarios where a full reset is acceptable or desired upon waking up. The application state may need to be persisted before going to sleep.
+- **Wake-Up Triggers**: The board can be configured to wake up either from an RTC alarm or an external interrupt pin.
 
 
 ## 📐 Measurements
@@ -32,16 +32,16 @@ Here's an overview of the reduction in power usage that you can expect from this
 | Deep Sleep       | On           | 11.57mA     |
 | Deep Sleep       | Off          | **58.99uA** |
 
-For more information about these measurements check out [this document](https://github.com/arduino-libraries/Arduino_LowPowerPortentaC33/blob/main/docs/README.md)
+For more information about these measurements check out [this page](./docs/)
 
-## Usage
-### Selecting a wakeup source
-The wakeup source can be one of the deep-sleep enabled wakeup pins, and an RTC Alarm. You can select multiple pins and the RTC alarm to wake up the board. 
+## 💻 Usage
+### Selecting a Wake-Up Source
+The wake-up source can be one of the deep-sleep enabled wake-up pins, and an RTC Alarm. You can select multiple pins and the RTC alarm to wake up the board. 
 
-#### Wakeup Pins
-This feature can be used when you want to wake up the board from external stimuli, such as sensors or user input. Some sensors have an interrupt pin that you can connect to one of the wakeup pins (eg: most motion sensors), while some output voltage on a pin, (eg: Passive Infrared Sensors or user buttons).
+#### 📍 Wake-Up Pins
+This feature can be used when you want to wake up the board from external stimuli, such as sensors or user input. Some sensors have an interrupt pin that you can connect to one of the wake-up pins (eg: most motion sensors), while others output a voltage on a pin when triggered (eg: Passive Infrared Sensors or user buttons).
 
-To select a wakeup pin just call `lowPower.setWakeupPin(<pin_number>, <direction>)`. The direction can be either **RISING** if you want to wake up when voltage is applied to a pin, or **FALLING** if you want to wake when no voltage is applied anymore. 
+To set up a wake-up pin call `lowPower.setWakeupPin(<pin_number>, <direction>)`. The direction can be either `RISING` if you want to wake up when voltage is applied to a pin, or `FALLING` if you want to wake when no voltage is applied anymore. 
 
 Here is a list of the usable interrupts: 
 
@@ -57,15 +57,14 @@ Here is a list of the usable interrupts:
 | D7          | P402    | IRQ4 |
 
 > [!IMPORTANT]  
-> Not all IRQs are created equal, the number of the IRQ represents it's priority. (IRQ0 being the highest priority and IRQ15 the lowest). Be careful when selecting your IRQ pin to make sure the board behaves as expected.
-
-#### RTC Alarm
-This feature is particularly useful when you want to set the board to wake up at specific times. You can use this in conjunction with the [RTC library](). 
-To make your board wake up on an RTC alarm you simply need to call `lowPower.setWakeupRTC()` and it will enable that functionality. Check out [this example]() for more details about setting up the RTC. 
+> Not all IRQs are created equal. The number of the IRQ represents it's priority. (`IRQ0` being the highest priority and `IRQ15` the lowest). Be careful when selecting your IRQ pin to make sure the board behaves as expected.
 
+#### ⏰ RTC Alarm
+This feature is particularly useful when you want to set the board to wake up at specific times. You can use this in conjunction with the [RTC library](https://github.com/arduino/ArduinoCore-renesas/tree/main/libraries/RTC). 
+To make your board wake up on an RTC alarm you simply need to call `lowPower.setWakeUpAlarm(time)` or `lowPower.setWakeUpAlarm(hours, minutes, seconds)`. Check out this [example](./examples/WakeFromRTC/) for more details about setting up the RTC.
 
-### Initiating sleep modes:
-Use lowPower.sleep() for Sleep Mode and lowPower.deepSleep() for Deep Sleep Mode. Upon calling these methods the board will sleep until one of the wakeup events mentioned earlier arises. 
 
+### 🛏️ Initiating sleep modes
+Use `lowPower.sleep()` to enter the Sleep Mode and `lowPower.deepSleep()` to enter the Deep Sleep Mode. Upon calling these methods the board will sleep until one of the wake-up events mentioned earlier arises. 
 
-For more information about this library check the [API Reference](https://github.com/arduino-libraries/Arduino_LowPowerPortentaC33/blob/main/docs/api.md)
+For more information on how to use this library check the [API Reference](./docs/api.md)

Diff for: docs/README.md

@@ -2,21 +2,20 @@
 
 The screenshots below are taken from the nRF Power Profiler application using a Nordic PPK2 while running the blink sketch on the same board. 
 
-
 #### Normal operating conditions
-![](https://raw.githubusercontent.com/arduino-libraries/Arduino_LowPowerPortentaC33/main/extras/results/normal_usage_blink.png)
+![](./assets/normal_usage_blink.png)
 
 #### Deep Sleep
 ##### Peripherals off
-![](https://raw.githubusercontent.com/arduino-libraries/Arduino_LowPowerPortentaC33/main/extras/results/deep_sleep_no_peripherals.png)
+![](./assets/deep_sleep_no_peripherals.png)
 
 ##### Peripherals on
-![](https://raw.githubusercontent.com/arduino-libraries/Arduino_LowPowerPortentaC33/main/extras/results/deep_sleep_peripherals_on.png)
+![](./assets/deep_sleep_peripherals_on.png)
 
 #### Sleep Mode 
 ##### Peripherals off
-![](https://raw.githubusercontent.com/arduino-libraries/Arduino_LowPowerPortentaC33/main/extras/results/sleep_no_peripherals.png)
+![](./assets/sleep_no_peripherals.png)
 
 ##### Peripherals on
-![](https://raw.githubusercontent.com/arduino-libraries/Arduino_LowPowerPortentaC33/main/extras/results/sleep_peripherals_on.png)
+![](./assets/sleep_peripherals_on.png)
 

Diff for: docs/api.md

@@ -18,7 +18,8 @@ This class allows the user to put the device into different low-power states and
 | [`sleep`](#class_low_power_1a351563f87f8d1f118e9d77201fd59a55) | Puts the device into a standard sleep mode. This sleep mode consumes less power than the active mode but more than the deep sleep mode. The device will resume execution from the point where it entered the sleep mode. |
 | [`deepSleep`](#class_low_power_1ada3410c10d04970e0898eb5f7f36ce55) | Puts the device into a deep sleep mode. The device consumes the least power in this mode but will reset when it wakes up effectively running the setup() function again. |
 | [`enableWakeupFromPin`](#class_low_power_1a9ee83fbc2b670ac9490cd179b2e08138) | Enables wake-up of the device from a specified pin (A0, A1, A2, A3, A4, A5, D4, D7 )  |
-| [`enableWakeupFromRTC`](#class_low_power_1a91d86cab239a56506bf15e9d2139c097) | Enables wake-up of the device based on the Real-Time Clock (RTC). |
+| [`setWakeUpAlarm`](#class_low_power_1ad9ccfd5502d837138fde0e60e5dc70e6) |  |
+| [`setWakeUpAlarm`](#class_low_power_1aeaa63e5a37b37ccb0379e9d2ade99941) |  |
 
 ## Members
 
@@ -62,12 +63,19 @@ Enables wake-up of the device from a specified pin (A0, A1, A2, A3, A4, A5, D4,
 * `direction` The direction of the interrupt that will wake up the device. (RISING, FALLING, CHANGE)
 <hr />
 
-### `enableWakeupFromRTC` <a id="class_low_power_1a91d86cab239a56506bf15e9d2139c097" class="anchor"></a>
+### `setWakeUpAlarm` <a id="class_low_power_1ad9ccfd5502d837138fde0e60e5dc70e6" class="anchor"></a>
 
 ```cpp
-void enableWakeupFromRTC()
+bool setWakeUpAlarm(RTCTime alarmTime)
+```
+
+<hr />
+
+### `setWakeUpAlarm` <a id="class_low_power_1aeaa63e5a37b37ccb0379e9d2ade99941" class="anchor"></a>
+
+```cpp
+bool setWakeUpAlarm(uint8_t hours, uint8_t minutes, uint8_t seconds)
 ```
 
-Enables wake-up of the device based on the Real-Time Clock (RTC).
 <hr />
 

Diff for: examples/WakeFromGPIO/WakeFromGPIO.ino renamed to examples/WakeFromPin/WakeFromPin.ino

@@ -1,38 +1,35 @@
 /*
-********************************************************************************
-*                          WakeFromGPIO.ino
-*
 * This example demonstrates how to wake up the Portenta C33 from deep sleep using a GPIO pin.
 * The pin can be configured to wake up the device on a rising or falling edge, but not all pins are supported.
 * Please check the README.md file for more information about the supported pins.
 *
-* The example uses two buttons connected to pin 0 and A3:
-*     * The device will go to sleep when the button connected to pin 0 is pressed.
+* The example uses two buttons connected to pin D0 and A3:
+*     * The device will go to sleep when the button connected to pin D0 is pressed.
 *     * The device will wake up when the button connected to pin A3 is pressed.
 * 
 * The example also demonstrates how to use the PF1550 PMIC to turn off the peripherals
 * before going to sleep and turn them back on after waking up.
-* uncomment #define TURN_PERIPHERALS_OFF on line 28 to enable this feature.
+* uncomment #define TURN_PERIPHERALS_OFF to enable this feature.
 *
-* When the device is not sleeping it will blink the built-in LED every 100ms. 
+* When the device is not sleeping it will blink the built-in LED. 
 * 
 * INSTRUCTIONS:
-* - Make sure you are running the latest version of the Renesas Core
+* - Make sure you are running the latest version of the Portenta C33 Core
 * - Select the Portenta C33 board from the Tools menu
-* - Select the Portenta C33 USB port from the Tools menu
+* - Select the Portenta C33's USB port from the Tools menu
 * - Upload the code to your Portenta C33
-* - Connect a button to pin 0 and with a pull-up resistor to 3.3V
-* - Connect a button to pin A3 and with a pull-up resistor to 3.3V 
+* - Connect a button to pin D0 and ground (internal pull-up resistor is enabled)
+* - Connect a button to pin A3 and ground (internal pull-up resistor is enabled) 
 * (If you need information about how to wire the buttons check this link: https://docs.arduino.cc/built-in-examples/digital/Button/)
 * 
-* Original author: C. Dragomir (http://arduino.cc)
+* Initial author: C. Dragomir
 */
 
 #include "Arduino_LowPowerPortentaC33.h"
 
-// #define TURN_PERIPHERALS_OFF
-#define SLEEP_PIN 0
-#define WAKE_PIN A3
+// #define TURN_PERIPHERALS_OFF // Uncomment this line to turn off the peripherals before going to sleep
+#define SLEEP_PIN D0 // Pin used to put the device to sleep
+#define WAKE_PIN A3 // Pin used to wake up the device
 
 LowPower lowPower;
 
@@ -59,14 +56,24 @@ LowPower lowPower;
 #endif
 
 void goToSleep(){
-    turnPeripheralsOff();
+    #ifdef TURN_PERIPHERALS_OFF
+        turnPeripheralsOff();
+    #else
+        // Turn off the built-in LED before going to sleep
+        digitalWrite(LED_BUILTIN, HIGH);
+    #endif
     lowPower.deepSleep(); 
 }
 
 void setup(){
-    lowPower = LowPower();
+    // Register the sleep and wake-up pins as inputs with pull-up resistors
+    pinMode(SLEEP_PIN, INPUT_PULLUP);
+    pinMode(WAKE_PIN, INPUT_PULLUP);
+
+    // Register the callback function to put the device to sleep when the button is pressed
     attachInterrupt(digitalPinToInterrupt(SLEEP_PIN), goToSleep, RISING);
     lowPower.enableWakeupFromPin(WAKE_PIN, RISING);
+    
     pinMode(LED_BUILTIN, OUTPUT);
 
     #ifdef TURN_PERIPHERALS_OFF
@@ -76,10 +83,11 @@ void setup(){
 }
 
 void loop(){
+    // Blink the built-in LED every 500ms when the device is not sleeping    
     digitalWrite(LED_BUILTIN, HIGH);
-    delay(100);
+    delay(500);
     digitalWrite(LED_BUILTIN, LOW);
-    delay(100);
+    delay(500);
 }