diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/api-overview/api-overview.md b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/api-overview/api-overview.md index 5fbb72caf3..c15c9cfab6 100644 --- a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/api-overview/api-overview.md +++ b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/api-overview/api-overview.md @@ -13,7 +13,7 @@ hardware: ## API List To access to any of these functions you need first to initialize an instance of the class **ArduinoAlvik()**. - +This reference is useful for both **MicroPython** and **C++ environments** as the functions were all created to have the same form across development environments meaning your experience should be easy to carry both options. ```arduino alvik = ArduinoAlvik() @@ -33,7 +33,7 @@ _Returns true if robot is on_ **Outputs** -- boolean: Returns true if robot is on, false if is off. +- boolean: Returns true if robot is on, false if it is off. ### `begin` @@ -75,7 +75,7 @@ _Returns the orientation of the IMU_ get_accelerations() -_Returns the 3-axial acceleration of the IMU_ +_Returns the 3-axial acceleration values of the IMU_ **Outputs** @@ -136,7 +136,7 @@ _Returns last acknowledgement_ **Outputs** -- **last_ack**: last acknowledgement value +- **last_ack**: last acknowledgement value. ### `get_battery_charge` @@ -146,7 +146,7 @@ _Returns the battery SOC_ **Outputs** -- **battery_soc**: percentage of charge +- **battery_soc**: percentage of charge. ### `get_touch_any` @@ -633,7 +633,7 @@ _Register callback when touch button RIGHT is pressed_ - **callback**: the name of the function to recall - **args**: optional arguments of the function -## Extras +## Function Parameters ### The Distance Unit @@ -677,6 +677,298 @@ Rotational speed unit of measurement used in the APIs: ### `"blocking" or "non blocking"` -While programming a microcontroller, the terms "blocking" means that **all the resources are used only in performing a specific action, and no other things can happen at the same time**. Usually this is used when you want to be precise or you don't want anything else that could interact with the action you are performing. +While programming a microcontroller, the term "blocking" means that **all the resources are used only in performing a specific action, and no other things can happen at the same time**. Usually this is used when you want to be precise or you don't want anything else that could interact with the action you are performing. + +On the other hand, "Non blocking", means that the microcontroller is free to do other things while the action is been performed. + +## Examples +These examples demonstrate practical implementations on how to use the Arduino Alvik API. Whether you're working with MicroPython or C++, these simple examples will help you understand how to implement various features in your projects, making it easy to get started with the Alvik in the language you're most comfortable with. + +### Simple Color Sensing Example + +This example demonstrates how to implement basic color sensing. The Alvik's color sensor reads the color of an object placed under it, and the detected color is printed to the console. + +- **Reference for MicroPython** + +```python +from arduino_alvik import ArduinoAlvik +from time import sleep_ms + +alvik = ArduinoAlvik() +alvik.begin() + +print("Alvik initialized for color sensing") + +while True: + color = alvik.get_color_label() + print(f"Detected color: {color}") + sleep_ms(500) +``` + +- **Reference for C++** + +```c +#include "Arduino_Alvik.h" + +Arduino_Alvik alvik; + +void setup() { + Serial.begin(9600); + alvik.begin(); + Serial.println("Alvik initialized for color sensing"); +} + +void loop() { + char* color = alvik.get_color_label(); + Serial.print("Detected color: "); + Serial.println(color); + delay(500); +} +``` + + + + +### Simple Directional Control + +This example demonstrates very basic control over the robot's movement based on directional arrow buttons. The Alvik will drive in the direction corresponding to the arrow button pressed (up, down, left, right). + +- **Reference for MicroPython** +```python +from arduino_alvik import ArduinoAlvik +from time import sleep_ms + +alvik = ArduinoAlvik() +alvik.begin() + +print("Alvik initialized") + +while True: + if alvik.get_touch_up(): + print("Moving Up") + alvik.drive(100, 0, linear_unit='cm/s') + sleep_ms(1000) + alvik.brake() + elif alvik.get_touch_down(): + print("Moving Down") + alvik.drive(-100, 0, linear_unit='cm/s') + sleep_ms(1000) + alvik.brake() + elif alvik.get_touch_left(): + print("Turning Left") + alvik.drive(0, 100, angular_unit='deg/s') + sleep_ms(1000) + alvik.brake() + elif alvik.get_touch_right(): + print("Turning Right") + alvik.drive(0, -100, angular_unit='deg/s') + sleep_ms(1000) + alvik.brake() + sleep_ms(100) + +``` +- **Reference for C++** + +```c +#include "Arduino_Alvik.h" + +Arduino_Alvik alvik; + +void setup() { + Serial.begin(9600); + alvik.begin(); + Serial.println("Alvik initialized"); +} + +void loop() { + if (alvik.get_touch_up()) { + Serial.println("Moving Up"); + alvik.drive(100, 0, "cm/s"); + delay(1000); + alvik.brake(); + } else if (alvik.get_touch_down()) { + Serial.println("Moving Down"); + alvik.drive(-100, 0, "cm/s"); + delay(1000); + alvik.brake(); + } else if (alvik.get_touch_left()) { + Serial.println("Turning Left"); + alvik.drive(0, 100, "deg/s"); + delay(1000); + alvik.brake(); + } else if (alvik.get_touch_right()) { + Serial.println("Turning Right"); + alvik.drive(0, -100, "deg/s"); + delay(1000); + alvik.brake(); + } + delay(100); +} +``` + +### Line Following + +This example demonstrates how to create a simple line-following robot. The code initializes the Alvik, reads sensor data to detect the line, calculates the error from the center of the line, and adjusts the Alvik's wheel speeds to follow the line. It also uses LEDs to indicate the direction the robot is turning. + +The Alvik starts when the OK `✔` button is pressed and stops when the Cancel button is pressed. The Alvik continuously reads the line sensors, calculates the error, and adjusts the wheel speeds to correct its path. + +- **Reference for MicroPython** + +```python +from arduino_alvik import ArduinoAlvik +from time import sleep_ms +import sys + + +def calculate_center(left: int, center: int, right: int): + centroid = 0 + sum_weight = left + center + right + sum_values = left + 2 * center + 3 * right + if sum_weight != 0: + centroid = sum_values / sum_weight + centroid = 2 - centroid + return centroid + + +alvik = ArduinoAlvik() +alvik.begin() + +error = 0 +control = 0 +kp = 50.0 + +alvik.left_led.set_color(0, 0, 1) +alvik.right_led.set_color(0, 0, 1) + +while alvik.get_touch_ok(): + sleep_ms(50) + +while not alvik.get_touch_ok(): + sleep_ms(50) + +try: + while True: + while not alvik.get_touch_cancel(): + + line_sensors = alvik.get_line_sensors() + print(f' {line_sensors}') + + error = calculate_center(*line_sensors) + control = error * kp + + if control > 0.2: + alvik.left_led.set_color(1, 0, 0) + alvik.right_led.set_color(0, 0, 0) + elif control < -0.2: + alvik.left_led.set_color(1, 0, 0) + alvik.right_led.set_color(0, 0, 0) + else: + alvik.left_led.set_color(0, 1, 0) + alvik.right_led.set_color(0, 1, 0) + + alvik.set_wheels_speed(30 - control, 30 + control) + sleep_ms(100) + + while not alvik.get_touch_ok(): + alvik.left_led.set_color(0, 0, 1) + alvik.right_led.set_color(0, 0, 1) + alvik.brake() + sleep_ms(100) + +except KeyboardInterrupt as e: + print('over') + alvik.stop() + sys.exit() +``` + +- **Reference for C++** + +```c +/* + This file is part of the Arduino_Alvik library. + + Copyright (c) 2024 Arduino SA + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at http://mozilla.org/MPL/2.0/. + +*/ + +#include "Arduino_Alvik.h" + +Arduino_Alvik alvik; + +int line_sensors[3]; +float error = 0; +float control = 0; +float kp = 50.0; + + + +void setup() { + Serial.begin(115200); + while((!Serial)&&(millis()>3000)); + alvik.begin(); + alvik.left_led.set_color(0,0,1); + alvik.right_led.set_color(0,0,1); + + while(!alvik.get_touch_ok()){ + delay(50); + } +} + +void loop() { + while (!alvik.get_touch_cancel()){ + + alvik.get_line_sensors(line_sensors[0], line_sensors[1], line_sensors[2]); + Serial.print(line_sensors[0]); + Serial.print("\t"); + Serial.print(line_sensors[1]); + Serial.print("\t"); + Serial.print(line_sensors[2]); + Serial.print("\n"); + error = calculate_center(line_sensors[0], line_sensors[1], line_sensors[2]); + control = error * kp; + if (control > 0.2){ + alvik.left_led.set_color(1,0,0); + alvik.right_led.set_color(0,0,0); + } + else{ + if (control < -0.2){ + alvik.left_led.set_color(0,0,0); + alvik.right_led.set_color(1,0,0); + } + else{ + alvik.left_led.set_color(0,1,0); + alvik.right_led.set_color(0,1,0); + } + } + + alvik.set_wheels_speed(30-control, 30+control); + delay(100); + } + + while (!alvik.get_touch_ok()){ + alvik.left_led.set_color(0,0,1); + alvik.right_led.set_color(0,0,1); + alvik.brake(); + delay(100); + } +} + +float calculate_center(const int left, const int center, const int right){ + float centroid = 0.0; + float sum_weight = left + center + right; + float sum_values = left + center * 2 + right * 3; + if (sum_weight!=0.0){ // divide by zero protection + centroid=sum_values/sum_weight; + centroid=-centroid+2.0; // so it is right on robot axis Y + } + return centroid; +} +``` + + + -On the other hand, "Non blocking", means that the microcontroller is free to do other thing while the action is been performed. diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/getting-started/getting-started.md b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/getting-started/getting-started.md index d79170d95f..ccc620ebee 100644 --- a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/getting-started/getting-started.md +++ b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/getting-started/getting-started.md @@ -29,7 +29,9 @@ Now that you have played with Alvik and have seen it moving, it is time to know ### Let's Start Coding Alvik -Alvik is intended to be programmed with MicroPyton. We recommend you to install the [Arduino Lab for MicroPython](https://labs.arduino.cc/en/labs/micropython) editor. Follow the instructions next to the download link to install it and open the IDE +Alvik is intended to be programmed with MicroPyton. We recommend you to install the [Arduino Lab for MicroPython](https://labs.arduino.cc/en/labs/micropython) editor. Follow the instructions next to the download link to install it and open the IDE. + +Alternatively, on par with other Arduino products, you can also program your Alvik using Arduino IDE and C++. If this is the case you can find setup instructions over at [Setting up Alvik on Arduino IDE](../setting-alvik-arduino-ide/setting-alvik-arduino-ide.md). Now that all the previous steps have been set, let's see how to make Alvik moving across your room while avoiding objects! Let's create custom program for Alvik that: diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/EsptoolSelection.png b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/EsptoolSelection.png new file mode 100644 index 0000000000..c0d7547745 Binary files /dev/null and b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/EsptoolSelection.png differ diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/UploadWithProgrammer.png b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/UploadWithProgrammer.png new file mode 100644 index 0000000000..d04c1e6af4 Binary files /dev/null and b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/UploadWithProgrammer.png differ diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/nano-esp32-gnd-b1.png b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/nano-esp32-gnd-b1.png new file mode 100644 index 0000000000..db909a7431 Binary files /dev/null and b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/nano-esp32-gnd-b1.png differ diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/uploadExample.png b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/uploadExample.png new file mode 100644 index 0000000000..4d3803b619 Binary files /dev/null and b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/assets/uploadExample.png differ diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/image.png b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/image.png new file mode 100644 index 0000000000..c765c6b861 Binary files /dev/null and b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/image.png differ diff --git a/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/setting-alvik-arduino-ide.md b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/setting-alvik-arduino-ide.md new file mode 100644 index 0000000000..9e8d03cc09 --- /dev/null +++ b/content/hardware/08.edu/solution-and-kits/alvik/tutorials/setting-alvik-arduino-ide/setting-alvik-arduino-ide.md @@ -0,0 +1,182 @@ +--- +title: "Setting up Alvik on Arduino IDE" +difficulty: beginner +description: "Learn how to configure your Alvik for Arduino IDE" +tags: + - Robot, MicroPython, Education +author: "Pedro Sousa Lima" +--- +The Arduino® Alvik robot was designed to be compatible with both C++ and MicroPython. To ensure a smooth experience, functions have the same structure and parameters across all environments. This means the [Alvik's API reference](https://docs.arduino.cc/tutorials/alvik/api-overview/) can be used as a resource regardless of which environment you choose. In this guide, we will prepare the board to be programmed using the Arduino IDE. + +## Requirements + +### Software + +- **Arduino IDE**: A modern desktop-based [Arduino IDE](https://support.arduino.cc/hc/en-us/articles/360019833020-Download-and-install-Arduino-IDE). +- **Alvik Library for Arduino**: A [library](https://github.com/arduino-libraries/Arduino_Alvik) that provides easy access to the Alvik robot's functionalities. +- **USB Drivers**: Ensure you have the correct drivers installed to communicate with Alvik via USB. + +### Hardware + +- **Alvik Robot**: The main platform you'll be programming. +- **USB Cable**: Used to connect Alvik to your computer for programming and power. +- **Computer**: Running Windows, macOS, or Linux with a USB port. + +## Setup + +### Arduino IDE + +1. Install the Arduino IDE from the [official Arduino website](https://www.arduino.cc/en/software). +2. Open the Arduino IDE. +3. Go to **Sketch > Include Library > Manage Libraries**. +4. In the Library Manager, search for "Alvik" and install the latest version of the Alvik library. + +### Firmware Preparation + +#### Preparing Alvik For Arduino IDE + +1. Connect pin **B1** to **GND** on the Alvik board. +![B1 and GND pins](assets/nano-esp32-gnd-b1.png) +3. While both pins are connected plug the Alvik board to your computer using the USB cable. +5. Select **esptool** as the programmer from the **Tools > Programmer** menu. +![Select programming tool esptool](assets/EsptoolSelection.png) +6. Select **Upload Using Programmer** from the **Sketch** menu. +![Upload with programmer option](assets/UploadWithProgrammer.png). You can now Press the **Reset** button on the board to make sure it is ready for uploading. +1. Now we can finally test it. Open the **Drive** example in the Arduino IDE by going to **File > Examples > Arduino_Alvik > drive**. +![Upload the drive example](assets/uploadExample.png) + +The Alvik should now start their motor. If no movement occurs make sure that: +- Alvik is **ON** +- Firmware is updated (more information available in the [User Manual](https://docs.arduino.cc/tutorials/alvik/user-manual/)). + + + +You can at any point revert back to the MicroPython programming environment by following the content available over at the [MicroPython installation guide](https://docs.arduino.cc/micropython/micropython-course/course/installation/). + +## Programming Alvik + +Now that your Alvik is correctly setup, lets go over some simple sketch uploads. If this is your first time with the Arduino IDE read how to [upload sketches here](https://support.arduino.cc/hc/en-us/articles/4733418441116-Upload-a-sketch-in-Arduino-IDE). + +### Libraries + +There are two libraries available in the library manager for use with Alvik: + +- **Arduino_Alvik**: This is the primary library we will use in our sketches, and it contains high-level commands for controlling the "brain" of the Alvik, which is the Nano ESP32 board. You can find more information and download it from [here](https://www.arduino.cc/reference/en/libraries/arduino_alvik/). + +- **Arduino_AlvikCarrier**: This library is designed for the STM board on the device and it is useful in situations where more fine control is required over commands. It allows more complex developments, especially when deeper integration with the hardware is needed. More information and the download link can be found [here](https://www.arduino.cc/reference/en/libraries/arduino_alvikcarrier/). + +### Print Firmware Version + +A simple but useful program if you are new to the Alvik is to understand how to get information from the onboard STM board. In this case, we are creating a simple sketch that prints the firmware version using the `get_version()` function. + +```c++ +#include "Arduino_Alvik.h" +``` + +Including the `Arduino_Alvik` library is essensial. The library contains all the needed predefined functions and classes that simplify the process of controlling the robot's hardware, such as motors and sensors. Without this include statement, the compiler wouldn't recognize the `Arduino_Alvik` class or its associated methods. + +```c++ +Arduino_Alvik alvik; +``` + +When using the Alvik livrary we declare an object of the `Arduino_Alvik` class named `alvik` in this case. All interactions with the robot will go through this `alvik` object. As with our `alvik.drive()` command. + +```c++ +void setup() { + alvik.begin(); + Serial.begin(115200); +} +``` + +In the `setup()` function, the `alvik.begin()` method initializes the Alvik robot. This will be a necessity on all sketches for the Alvik. + +```c++ +void loop() { + + uint8_t u,m,l; + + alvik.get_version(u,m,l); // Gets the firmware version + Serial.printf("%d.%d.%d\n", u, m, l); + alvik.drive(10, 45); + delay(1000); // Waits a second + alvik.drive(10, -45); + delay(1000); // Waits a second + +} +``` + +This code continuously retrieves and prints the firmware version thanks to the ```get_version()``` every second while making the Alvik robot's wheels rotate back and forth using the ```drive()``` command. + + +**Complete code:** + +```c++ +#include "Arduino_Alvik.h" + +Arduino_Alvik alvik; + +void setup() { + alvik.begin(); + Serial.begin(115200); +} + +void loop() { + + uint8_t u,m,l; + + alvik.get_version(u,m,l); // Gets the firmware version + Serial.printf("%d.%d.%d\n", u, m, l); + alvik.drive(10, 45); + delay(1000); // Waits a second + alvik.drive(10, -45); + delay(1000); // Waits a second + +} +``` + +### Obstacle Avoider Example In C++ + +A more complex example can be found in the [getting started](https://docs.arduino.cc/tutorials/alvik/getting-started/) guide for the Alvik. +Due to the functions having same structure and names on both MicroPython and C++ we can easily port the ```obstacle-avoider``` to C++. + +Keeping in mind the initialization of the Alvik from the previous example, we can build the example on the Arduino IDE: + +```c++ +#include "Arduino_Alvik.h" + +Arduino_Alvik alvik; + +void setup() { + alvik.begin(); + delay(5000); // Waiting for the robot to setup +} + +void loop() { + float distance = 12.0; + float degrees = 45.0; + float speed = 10.0; + + float distance_l, distance_cl, distance_c, distance_r, distance_cr; + + alvik.get_distance(distance_l, distance_cl, distance_c, distance_r, distance_cr); + delay(50); + + Serial.println(distance_c); + + if (distance_c < distance || distance_cl < distance || distance_cr < distance || distance_l < distance || distance_r < distance) { + alvik.rotate(degrees); + } else { + alvik.drive(speed, 0.0); + } +} + +``` + +You can now explore the other included examples that cover more of the Alvik's components and more functions listed on our [API reference](https://docs.arduino.cc/tutorials/alvik/api-overview/). + + +## More Resources + +- **[Alvik Documentation](https://docs.arduino.cc/hardware/alvik/)**: Dive deeper into the capabilities of Alvik by exploring the official documentation. +- **[Community Forums](https://forum.arduino.cc/search?q=alvik)**: Join the Arduino community forums to ask questions and share your projects. +- **[Tutorials and Projects](https://courses.arduino.cc/explore-robotics-micropython/)**: Look for tutorials and project ideas that can inspire your next steps with Alvik.