Skip to content
This repository was archived by the owner on Aug 11, 2021. It is now read-only.

Commit 230dbc5

Browse files
i-herreraLenardgeorge
authored and
sebromero
committed
usb-tutorial-draft (#10)
* Created new tutorial * Updated content.md file * Update content.md * Update content.md Co-authored-by: Lenard George Swamy <lenardgeorge92@gmail.com>
1 parent 287b5f1 commit 230dbc5

File tree

1 file changed

+5
-217
lines changed
  • content/tutorials/portenta-h7/por-ard-usb

1 file changed

+5
-217
lines changed

‎content/tutorials/portenta-h7/por-ard-usb/content.md‎

Lines changed: 5 additions & 217 deletions
Original file line numberDiff line numberDiff line change
@@ -1,226 +1,14 @@
1-
# Portenta H7 as a USB Host
1+
# Setting Up Portenta H7 For Arduino
2+
It is possible to configure Portenta H7 to behave as a USB host in a way that we can connect peripherals such as keyboard or mouse to interact with the board. This way we could connect a keyboard to our portenta and input numbers or characters into our programs.
23

3-
It is possible to configure Portenta H7 to act as a USB host in a way that we can connect peripherals such as a keyboard or mouse to interact with the board. This way you could connect a keyboard to your Portenta and type numbers or characters to interact with the board.
44
## What you will learn
5-
65
- How to configure the Portenta H7 as a USB host
7-
- How to use the *KeyboardController* library to establish USB communication with Portenta H7
8-
- To write a small program that reads button presses from a keyboard
9-
- How to debug the data that we send from the peripheral to the Portenta H7 using an additional Arduino board.
6+
- What type of peripherals can we connect and how
7+
- To write a small program to read button presses from a keyboard
108

119
## Required hardware and software
12-
1310
- Portenta H7 board (<https://store.arduino.cc/portenta-h7>)
14-
- USB-C cable (either USB-A to USB-C or USB-C to USB-C)
15-
- USB-C adapter (you can find [here](https://www.dustin.se/product/5011166993/travel-port-usb-c-total) the one we used for the tutorial)
16-
- External keyboard
11+
- USB C cable (either USB A to USB C or USB C to USB C)
1712
- Arduino IDE 1.8.10+ or Arduino Pro IDE 0.0.4+
18-
- Power supplier for the USB adapter (I don't know how to call this)
19-
20-
### Extra materials
21-
22-
- Arduino Arduino MKR WiFi 1010 (or other board with at least two serial ports, check [here](https://www.arduino.cc/reference/en/language/functions/communication/serial/) the list of Arduino boards with more than one serial port.)Arduino IDE 1.8.10+ or Arduino Pro IDE 0.0.4+
23-
- USB cable compatible with the Arduino Arduino MKR WiFi 1010 (or the board you have selected)
24-
- 3 Jumper wires
25-
26-
![The Arduino core is built on top of the Mbed stack](assets/Arduino-Logo.svg)
27-
28-
29-
# Setting Up the USB host
30-
31-
In this tutorial you are going to convert your Portenta in a USB Host that will allow you, by using a keyboard, to toggle the RGB built-in LEDs of the board. Throughout the tutorial, you will learn how to connected the keyboard to the Portenta board and how to program the board to become it in a USB Host device.
32-
33-
## 1. The Basic Setup
34-
35-
Begin by plugging in your Portenta board to the computer using a USB-C cable and open the Arduino IDE or the Arduino Pro IDE. If this is your first time running Arduino sketch files on the board, we suggest you check out how to [set up the Portenta H7 for Arduino](https://www.arduino.cc/pro/tutorials/portenta-h7/por-ard-gs) before you proceed.
36-
37-
![The Portenta H7 can be connected to the computer using an appropriate USB-C cable](assets/por_ard_usbh_basic_setup.svg)
38-
39-
## 2. Creating the keyboard controller
40-
41-
Now, let's create a sketch that handles the USB connections and modify the state of the LEDs with each press on the r(R), g(G) or b(B) keys, so when you press the key first time the LEDs will switch on and to turn them off, you will need to press the corresponding key again.
42-
43-
As programming the USB protocol that allows the board handle USB devices is an arduous task, you will use an already built example called KeyboardController, to find it, first, make sure you select Arduino Portenta H7 (M7 core) as the board.
44-
45-
![Select the Arduino Portenta H7 (M7 core) in the board selector.](assets/por_ard_usbh_select_board.png)
46-
47-
Then, open: File>Examples>USBHOST>KeyboardController
48-
49-
![Open the Keyboard Controller example.](assets/por-ard-usbh-keyboardController.png)
50-
51-
The **USBHost.h** library that is used in this example is a revamp of the classic Arduino **USBHost.h** library. This new version, among adapting the protocol to the USB newer versions, allows to connect devices through HUBs () USB adapters). For a better understanding about how the USBHost library works, it could be helpful for you to take a look at the Arduino [USBHost.h](https://www.arduino.cc/en/Reference/USBHost) library.
52-
53-
## 3. Detecting the keys from the keyboard
54-
55-
The example you have opened describes how the board will handle the connection with a keyboard, addressing the functionality of each one of the keys of it. In order to detect which one of the keys from the keyboard is pressed, you will need to modify and add some lines of code to the example.
56-
57-
Let's start by removing the comment line ( `//` ) of the following line `.on_key = process_key` at the beginning of the code. By doing this, each time you press a key, the program calls the function that converts the data received from the keyboard from `HEX` to `char`.
58-
59-
```cpp
60-
static const tusbh_boot_key_class_t cls_boot_key = {
61-
.backend = &tusbh_boot_keyboard_backend,
62-
//.on_key = process_key
63-
};
64-
```
65-
66-
Then, in order to modify the state of the LEDs of the board with the r(R), g(G) or b(B) keys, you need to add the following portion of code inside the `process_key()` function, as shown in the image below:
67-
```cpp
68-
if (ch == 'r' || ch == 'R')
69-
{
70-
ledRstate = !ledRstate;
71-
if (ledRstate == 1)
72-
digitalWrite(LEDR, LOW);
73-
else
74-
digitalWrite(LEDR, HIGH);
75-
}
76-
77-
if (ch == 'g' || ch == 'G')
78-
{
79-
ledGstate = !ledGstate;
80-
if (ledGstate == 1)
81-
digitalWrite(LEDG, LOW);
82-
else
83-
digitalWrite(LEDG, HIGH);
84-
}
85-
86-
if (ch == 'b' || ch == 'B')
87-
{
88-
ledBstate = !ledBstate;
89-
if (ledBstate == 1)
90-
digitalWrite(LEDB, LOW);
91-
else
92-
digitalWrite(LEDB, HIGH);
93-
}
94-
```
95-
96-
![Code to toggle the LEDs with the R, G and B keys ](assets/por_ard_usbh_key_led-control.png)
97-
98-
## 4. Initializing the LEDs
99-
100-
Once you have the code that is going to detect if the correct keys are pressed and control the LEDs in function on them, you need ot initialise the LEDs, to do so, let's add the following portion of code inside the `setup()` function.
101-
```cpp
102-
pinMode(LEDR, OUTPUT);
103-
pinMode(LEDG, OUTPUT);
104-
pinMode(LEDB, OUTPUT);
105-
106-
//Turn off the LEDs
107-
digitalWrite(LEDR, HIGH);
108-
digitalWrite(LEDG, HIGH);
109-
digitalWrite(LEDB, HIGH);
110-
```
111-
112-
And then, to finish with the code edition, you need to initialize ledRstate, ledGstate and ledBstate variables as boolean, by adding this portion of code before the `setup()` function.
113-
114-
```cpp
115-
bool ledRstate = 0;
116-
bool ledGstate = 0;
117-
bool ledBstate = 0;
118-
```
119-
120-
## 5. Upload the Code
121-
122-
Before uploading the sketch to the board, save it you sketchbook and name it **leds_keyController.ino**. Then select the **Arduino Portenta H7 (M7 core)** from the **Board** menu and the port the Portenta is connected to. Upload the **leds_keyController.ino** sketch. Doing so will automatically compile the sketch beforehand.
123-
124-
![Select the Arduino Portenta H7 (M7 core) in the board selector.](assets/por_ard_usbh_upload_sketch.png)
125-
126-
## 6. Conecting a keyboard to Portenta
127-
128-
When you connect the Portenta board to the computer to program it, the computer is the USB host and the Portenta board is the USB slave, same happens when you connect a external keyboard to your PC. In this case, the Portenta board will be the host, it won't be connected to the PC, let's see how to make the connections.
129-
130-
![Schema connection.](assets/por_ard_usbh_connections_schema.png)
131-
132-
In the image above you can see that:
133-
134-
+ The Portenta is connected to the "TO HOST" port from the HUB (USB C adapter)
135-
+ The HUB (USB C adapter) needs to be powered externaly with a power supplier, it is needed to provide power to Portenta
136-
+ You should connect the keyboard to the HUB (USB C adapter) in the same way you would connect it to your PC
137-
138-
## 7. Toggeling the LEDs
139-
140-
Once you have connected your portenta board, you should be able to toggle the LEDs by pressing the R, G or B keys.
141-
142-
![Toggle the LEDs by pressing the R, G or B keys on the keyboard.](assets/por_ard_usbh_working_demo.png)
143-
144-
If it doesn't work as it should try:
145-
146-
1. Reset the portenta by pressing the Reset button. ![Reset Button.](assets/por_ard_usbh_reset.png)
147-
2. Disconnect the Portenta board from the HUB (USB C adapter), disconnect the power from the HUB, connect the Portenta to the HUB and connect the power to the HUB.
148-
149-
# Conclusion
150-
151-
This tutorial shows how to connect and control a keyboard by configuring Portenta as an USB Host. On it, you also learnt how to modify one of the already build examples for Portenta to have a visual reference of the interactions between the keyboard and Portenta.
152-
153-
# Next Steps
154-
155-
Now that you've learnt how to set up the board as a USB Host and understood how the example works, start experimenting with the **KeyboardController.ino** sketch. This sketch can be tweaked in a variety of ways based on your needs. For example, you can add a mouse to the HUB and increase the bright of one of the LEDs of the board when pressing the left button and increase the bright of it when pressing the right button of the mouse.
156-
157-
# Troubleshooting
158-
159-
## LEDs not toggeling troubleshooting
160-
161-
This troubleshooting will guide you to find why the LEDs of your Portenta don't toggle when you press the keys on the keyboard, to do so, you will need some extra components such as:
162-
163-
* Arduino Arduino MKR WiFi 1010 board (or other Arduino board with at least two serial ports)
164-
* USB cable to connect the extra board to the PC
165-
* 3 jumper wires
166-
167-
To detect what the problem is about, we are going to send all the information about the USB peripheral (in this case the keyboard) through serial communication from Portenta to the Arduino MKR WiFi 1010 board. Once this info arrives to the Arduino MKR WiFi 1010 board, we will print it out through the Serial Monitor, which will allow us to debug what can be happening.
168-
169-
### 1. Connect the Portenta to the Arduino MKR WiFi 1010
170-
171-
To connect thePortenta to the Arduino MKR WiFi 1010 board you will need connect the pins with Serial1 functionality (13RX and 14TX in both boards) between them as shown in the image below. Don't forget to connect as well the GNDs of the boards.
172-
173-
![Serial connection Portenta - Arduino MKR WiFi 1010.](assets/por_ard_usbh_portenta_to_mkr1010.png)
174-
175-
### 2. Program the Arduino MKR WiFi 1010 board
176-
177-
To set up Arduino MKR WiFi 1010 board copy the following code, paste it into a new sketch file and name it **mkr1010_serial.ino**. Then upload it to the Arduino Arduino MKR WiFi 1010 board. Make sure you select **Arduino MKR WiFi 1010** as the board and the port to which the Arduino MKR WiFi 1010 is connected.
178-
179-
```cpp
180-
char data;
181-
182-
void setup()
183-
{
184-
Serial.begin(9600);
185-
Serial1.begin(115200);
186-
}
187-
188-
void loop()
189-
{
190-
191-
if (Serial1.available())
192-
{
193-
data = Serial1.read();
194-
Serial.write(data);
195-
}
196-
}
197-
```
198-
199-
### 3. System schema connection
200-
201-
After connecting the Portenta board to the Arduino MKR WiFi 1010 and programmed your Arduino MKR WiFi 1010 board, the schema connection you have should be similar to the followint one:
202-
203-
![Troubleshooting full connection schema.](assets/por_ard_usbh_full_connections_schema.png)
204-
205-
206-
207-
### 3. Open the Serial Monitor of the Arduino MKR WiFi 1010 board
208-
209-
Once you have everything connected, open the Serial Monitor and reset the Portenta. After resetting the Portenta board, your Serial Monitor should display something similar to the following image:
210-
211-
![Troubleshooting USB communication info.](assets/por_ard_usbh_serial_info.png)
212-
213-
In the info received on the MKR WiFi 1010 board you should see some "Enabled" messages. It means that the Portenta recognise the different ports of your HUB. If you can see them, when you press any key of the keyboard, it should be printed on the Serial Monitor.
214-
215-
If in the messages received on the MKR WiFi 1010 board you see any "Disabled" message, it means that something went wrong with the communication of the HUB and the Portenta board. If this happens try:
216-
217-
1. Reset the Portenta by pressing the reset button.
218-
2. Disconnect the Portenta board from the HUB (USB C adapter), disconnect the power from the HUB, connect the Portenta to the HUB and connect the power to the HUB.
219-
220-
If, after repeating this process several times, the connection still isn't working, the HUB you are using may not be compatible with the Portenta board and you will need a different HUB to complete this tutorial.
221-
22213

22314

224-
**Authors:** Jose Garcia
225-
**Reviewed by:** Sebastian Hunkeler
226-
**Last revision:**

0 commit comments

Comments
 (0)