plat_nina.md 3.28 KB
Newer Older
Ricardo Quesada's avatar
Ricardo Quesada committed
1
# Bluepad32 firmware for NINA
Ricardo Quesada's avatar
Ricardo Quesada committed
2
3
4
5
6
7

## What is NINA

NINA is a family of [ESP32 modules][nina-esp32].
These modules are present on some Arduino boards like:

8
9
10
- [Arduino Nano RP2040 Connect][nano_rp2040]
- [Arduino Nano 33 IoT][nano_33_iot]
- [Arduino MKR WiFi 1010][mkr_wifi]
Ricardo Quesada's avatar
Ricardo Quesada committed
11
12
13

NINA modules are co-processors, usually used only to bring WiFi or BLE to the main processor.

14
15
16
In order to have gamepad support, the original NINA firmware must be replaced
with Bluepad32 firmware. This is a simple step that needs to be done just once,
and can be "undone" at any time.
Ricardo Quesada's avatar
Ricardo Quesada committed
17

Ricardo Quesada's avatar
Ricardo Quesada committed
18
![how-does-it-work](images/bluepad32-nina-how-does-it-work.png)
19

20
21
This is how it works:

22
- Gamepad (A) talks to NINA module (B)
23
- NINA module (B) talks to main processor (C)
24
25

Bluepad32 firmware is "compatible-enough" with the original firmware:
Ricardo Quesada's avatar
Ricardo Quesada committed
26
27

- Uses SPI, and the same GPIOs to talk to the main processor
28
29
30
- Uses the same protocol that runs on top of SPI
- But not all messages are implemented. Only the ones that are needed
  to have gamepad support working.
Ricardo Quesada's avatar
Ricardo Quesada committed
31

Ricardo Quesada's avatar
Ricardo Quesada committed
32
33
[nina-esp32]: https://www.u-blox.com/en/product/nina-w10-series-open-cpu
[nina-fw]: https://github.com/arduino/nina-fw
34
35
36
[nano_rp2040]: https://store.arduino.cc/usa/nano-rp2040-connect-with-headers
[nano_33_iot]: https://store.arduino.cc/usa/nano-33-iot
[mkr_wifi]: https://store.arduino.cc/usa/mkr-wifi-1010
Ricardo Quesada's avatar
Ricardo Quesada committed
37

Ricardo Quesada's avatar
Ricardo Quesada committed
38
## Flashing Bluepad32 firmware
Ricardo Quesada's avatar
Ricardo Quesada committed
39

Ricardo Quesada's avatar
Ricardo Quesada committed
40
To flash Bluepad32 firmware, you have to:
Ricardo Quesada's avatar
Ricardo Quesada committed
41

Ricardo Quesada's avatar
Ricardo Quesada committed
42
43
44
1. Put the Arduino board in "pass-through" mode
2. Flash pre-compiled version
3. Or compile it yourself and flash it.
Ricardo Quesada's avatar
Ricardo Quesada committed
45

Ricardo Quesada's avatar
Ricardo Quesada committed
46
### 1. Put Arduino board in "passthrough" mode
Ricardo Quesada's avatar
Ricardo Quesada committed
47

Ricardo Quesada's avatar
Ricardo Quesada committed
48
Before flash Bluepad32 firmware, you have to put the Arduino board in "pass-through" mode:
Ricardo Quesada's avatar
Ricardo Quesada committed
49

Ricardo Quesada's avatar
Ricardo Quesada committed
50
51
52
1. Open Arduino IDE
2. Install the WiFiNINA library (just do it once)
3. And finally open the `SerialNINAPassthrough` sketch:
Ricardo Quesada's avatar
Ricardo Quesada committed
53

Ricardo Quesada's avatar
Ricardo Quesada committed
54
- File -> Examples -> WiFiNINA -> Tools -> SerialNINAPassthrough
Ricardo Quesada's avatar
Ricardo Quesada committed
55

Ricardo Quesada's avatar
Ricardo Quesada committed
56
Compile it and flash it to the Arduino board.
Ricardo Quesada's avatar
Ricardo Quesada committed
57

Ricardo Quesada's avatar
Ricardo Quesada committed
58
### 2. Flash a pre-compiled firmware
Ricardo Quesada's avatar
Ricardo Quesada committed
59

Ricardo Quesada's avatar
Ricardo Quesada committed
60
You can grab a precompiled firmware from here (choose latest version):
Ricardo Quesada's avatar
Ricardo Quesada committed
61

62
- https://gitlab.com/ricardoquesada/bluepad32/tags
Ricardo Quesada's avatar
Ricardo Quesada committed
63

Ricardo Quesada's avatar
Ricardo Quesada committed
64
And download the `bluepad32-nina-xxx.zip` file.
Ricardo Quesada's avatar
Ricardo Quesada committed
65

Ricardo Quesada's avatar
Ricardo Quesada committed
66
Unzip it, and follow the instructions described in the `README.md` file.
Ricardo Quesada's avatar
Ricardo Quesada committed
67

Ricardo Quesada's avatar
Ricardo Quesada committed
68
### 3. Or compile it yourself and flash it
Ricardo Quesada's avatar
Ricardo Quesada committed
69

70
Install the requirements described here: [README.md][readme].
Ricardo Quesada's avatar
Ricardo Quesada committed
71

Ricardo Quesada's avatar
Ricardo Quesada committed
72
Chose `nina` as the target platform:
Ricardo Quesada's avatar
Ricardo Quesada committed
73

Ricardo Quesada's avatar
Ricardo Quesada committed
74
```sh
75
cd ${BLUEPAD32}/src
Ricardo Quesada's avatar
Ricardo Quesada committed
76

77
78
79
# Select Nina platform:
# Components config -> Bluepad32 -> Target Platform -> Nina
idf.py menuconfig
Ricardo Quesada's avatar
Ricardo Quesada committed
80
81

# And then compile it!
82
idf.py build
Ricardo Quesada's avatar
Ricardo Quesada committed
83
84
```

85
On Nano 32 IoT / MKR WIFI 1010, doing `idf.py flash` will just work.
Ricardo Quesada's avatar
Ricardo Quesada committed
86
87

```sh
Ricardo Quesada's avatar
Ricardo Quesada committed
88
89
90
91
92
# Only valid for:
#   * the Nano 33 IoT
#   * MKR WIFI 1010

# Port might be different
93
export ESPPORT=/dev/ttyACM0
Ricardo Quesada's avatar
Ricardo Quesada committed
94

95
idf.py flash
Ricardo Quesada's avatar
Ricardo Quesada committed
96
97
```

Ricardo Quesada's avatar
Ricardo Quesada committed
98
99
But on NANO RP2040 Connect, you have to flash it using the `--before no_reset` option,
and **NOT** `--before default_reset`. E.g:
Ricardo Quesada's avatar
Ricardo Quesada committed
100
101

```sh
Ricardo Quesada's avatar
Ricardo Quesada committed
102
103
104
105
# Only valid for:
#   * Nano RP2040 Connect

# Port might be different
106
export ESPPORT=/dev/ttyACM0
Ricardo Quesada's avatar
Ricardo Quesada committed
107

108
esptool.py --port ${ESPPORT} --baud 115200 --before no_reset write_flash 0x1000 ./build/bootloader/bootloader.bin 0x10000 ./build/bluepad32-airlift.bin 0x8000 ./build/partitions_singleapp.bin
Ricardo Quesada's avatar
Ricardo Quesada committed
109
110
```

Ricardo Quesada's avatar
Ricardo Quesada committed
111
112
[readme]: https://gitlab.com/ricardoquesada/bluepad32/-/blob/master/README.md

Ricardo Quesada's avatar
Ricardo Quesada committed
113
114
## Example

Ricardo Quesada's avatar
Ricardo Quesada committed
115
The Bluepad32 library for Arduino with examples is available here:
116

117
- http://gitlab.com/ricardoquesada/bluepad32-arduino