plat_airlift.md 5.77 KB
Newer Older
Ricardo Quesada's avatar
Ricardo Quesada committed
1
# Bluepad32 firmware for AirLift
Ricardo Quesada's avatar
Ricardo Quesada committed
2
3
4

## What is AirLift

5
6
AirLift is an [ESP32][esp32] module. This module is a "co-processor",
usually used to bring WiFi or BLE to the main processor.
Ricardo Quesada's avatar
Ricardo Quesada committed
7

8
AirLift modules are present in some [Adafruit][adafruit] boards, like in:
Ricardo Quesada's avatar
Ricardo Quesada committed
9

10
11
12
13
14
* [MatrixPortal M4][matrixportal-m4]
* [PyPortal][pyportal]
* [PyBadge][pybadge]
* [Metro M4 Express AirLift][metro-m4-airlift]

15
Or it can be a standalone board:
16
17
18
19
20
21

* [AirLift module][airlift-module]

AirLift modules come pre-installed with [Adafruit's NINA firmware][nina-fw].

**NOTE**: [Adafruit's NINA][nina-fw] firmware is a fork of [Arduino's NINA][arduino-nina] firmware.
22
They are pretty similar, but they are not compatible since they use different SPI pins.
23
24
25
26
27

In order to have gamepad support, the original AirLift 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
28
![how-does-it-work](images/bluepad32-airlift-how-does-it-work.png)
29

30
31
This is how it works:

32
* Gamepad (A) talks to AirLift module (B)
33
* AirLift module (B) talks to main processor (C)
34
35

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

* Uses SPI, and the same GPIOs to talk to the main processor
38
39
* Uses the same protocol that runs on top of SPI
* But not all messages are implemented. Only the ones that are needed
Ricardo Quesada's avatar
Ricardo Quesada committed
40
41
42
  to have gamepad support working.

[adafruit]: https://www.adafruit.com
43
44
45
46
47
48
49
50
[airlift-module]: https://www.adafruit.com/product/4201
[arduino-nina]: https://github.com/arduino/nina-fw
[esp32]: https://www.espressif.com/en/products/socs/esp32
[matrixportal-m4]: https://www.adafruit.com/product/4745
[metro-m4-airlift]: https://www.adafruit.com/product/4000
[nina-fw]: https://github.com/adafruit/nina-fw
[pybadge]: https://www.adafruit.com/product/4200
[pyportal]: https://www.adafruit.com/product/4116
Ricardo Quesada's avatar
Ricardo Quesada committed
51

Ricardo Quesada's avatar
Ricardo Quesada committed
52
## Flashing Bluepad32 firwmare
53

Ricardo Quesada's avatar
Ricardo Quesada committed
54
To flash Bluepad32 firmware, you have to:
55

Ricardo Quesada's avatar
Ricardo Quesada committed
56
57
58
1. Put the Adafruit board in "pass-through" mode
2. Flash pre-compiled version
3. Or compile it yourself and flash it.
59

Ricardo Quesada's avatar
Ricardo Quesada committed
60
### 1. Put Adafruit board in "passthrough" mode
61

Ricardo Quesada's avatar
Ricardo Quesada committed
62
Might slightly vary from board to board, but basically what you have to do is:
63

Ricardo Quesada's avatar
Ricardo Quesada committed
64
65
66
1. Put the board in "boot" mode, usually by double pressing the "reset" button.
2. Flash the right "Passthrough" firmware for your board.
   * Details here: [Adafruit's Upgrade AirLift firmware][adafruit-airlift-upgrade]
Ricardo Quesada's avatar
Ricardo Quesada committed
67

Ricardo Quesada's avatar
Ricardo Quesada committed
68
[adafruit-airlift-upgrade]: https://learn.adafruit.com/upgrading-esp32-firmware/upgrade-an-airlift-all-in-one-board
Ricardo Quesada's avatar
Ricardo Quesada committed
69

Ricardo Quesada's avatar
Ricardo Quesada committed
70
### 2. Flash pre-compiled version
Ricardo Quesada's avatar
Ricardo Quesada committed
71

Ricardo Quesada's avatar
Ricardo Quesada committed
72
Download latest pre-compiled version from here:
Ricardo Quesada's avatar
Ricardo Quesada committed
73

Ricardo Quesada's avatar
Ricardo Quesada committed
74
75
76
77
78
* https://github.com/ricardoquesada/bluepad32/tags

Unzip it, and follow the instructions described in the `README.md` file.

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

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

Ricardo Quesada's avatar
Ricardo Quesada committed
82
Chose `airlift` as the target platform:
Ricardo Quesada's avatar
Ricardo Quesada committed
83

Ricardo Quesada's avatar
Ricardo Quesada committed
84
```sh
85
cd {BLUEPAD32}/src/
Ricardo Quesada's avatar
Ricardo Quesada committed
86

87
88
89
# Select AirLift platform:
# Components config -> Bluepad32 -> Target Platform -> AirLift
idf.py menuconfig
Ricardo Quesada's avatar
Ricardo Quesada committed
90

Ricardo Quesada's avatar
Ricardo Quesada committed
91
# And then compile it!
92
idf.py build
Ricardo Quesada's avatar
Ricardo Quesada committed
93
```
Ricardo Quesada's avatar
Ricardo Quesada committed
94

Ricardo Quesada's avatar
Ricardo Quesada committed
95
To flash it, you have to use the `--before no_reset` option:
96

Ricardo Quesada's avatar
Ricardo Quesada committed
97
```sh
Ricardo Quesada's avatar
Ricardo Quesada committed
98
99
100
# Flash it!

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

103
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
104
105
```

Ricardo Quesada's avatar
Ricardo Quesada committed
106
[readme]: https://gitlab.com/ricardoquesada/bluepad32/-/blob/master/README.md
Ricardo Quesada's avatar
Ricardo Quesada committed
107
108
109
[matrix_portal_m4]: https://learn.adafruit.com/adafruit-matrixportal-m4
[passthrough firmware]: https://learn.adafruit.com/adafruit-airlift-breakout/upgrade-external-esp32-airlift-firmware

Ricardo Quesada's avatar
Ricardo Quesada committed
110
## CircuitPython example
Ricardo Quesada's avatar
Ricardo Quesada committed
111

Ricardo Quesada's avatar
Ricardo Quesada committed
112
The Bluepad32 library for CircuitPython, including a working example is available here:
Ricardo Quesada's avatar
Ricardo Quesada committed
113

114
* https://gitlab.com/ricardoquesada/bluepad32-circuitpython
115

116
117
## How to debug Bluepad32 for AirLift

Ricardo Quesada's avatar
Ricardo Quesada committed
118
119
**ADVANCED**: Normally you wouldn't need this.

120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
Assuming that the ESP32 UART pins are not exposed (true for all AirLift modules),
the recommended way to debug the Bluepad32 firmware is:

* Get any ESP32 breakout module. It could be an [Adafruit HUZZAH32][esp32-adafruit] or [any other ESP32 breakout][amazon-esp32].
  * JUST DON'T GET A ESP32-S2 (doesn't have Bluetooth!). JUST "ESP32"
* Get a SAMD51 module, like the [Adafruit Feather M4 Express][feather_m4]
* Wire it like this:

|       | ESP32 | SAMD51 |
|-------|-------|--------|
| MOSI  | 14    | MOSI   |
| MISO  | 23    | MISO   |
| SCK   | 18    | SCK    |
| CS    | 5     | D10    |
| READY | 33    | D9     |
| RESET | EN    | D6     |

137
138
139
140
Something like this (left: Feather M4 express, right: HUZZAH32)

![fritzing](https://lh3.googleusercontent.com/pw/ACtC-3fNxNMUdaoBg7DGB6OPPDDnu_DQ15fmJS_I3crWjFKg7k3DA4HDeI8I_SUicSFamGuIVsHpM-myo5h-v1YOOFUU7lz6mU5tyExXDWZXedaYbUxhgf-GXfeZhMCdJCt1nZ04zFb1nyH86-pvZqc8yG9Y4A=-no)

141
NOTE: If you use a HUZZAH32, pay attention to the GPIO labels. The MOSI/MISO/SCK lables that are in the front of board, are not the ones that you should use. See the back of the board for the correct GPIO numbers.
142
143

In real life it might look more messy:
144
145
146

![wiring](https://lh3.googleusercontent.com/pw/ACtC-3dutrQXEj9I5zicNFW3K3PBbfge7MdwgB8dyi-wPSrtSp8zku3Y4c9WtBqQ9Bfa92xOjgSkZncAuzAZyc5F392tFkzkqWUl4YkfrKrM4e8TGP-B_7I7G_fRvFbIYbEQQIi-LlOnPU5SdGYYeW6hxxpJ_w=-no)

147
The benefits of using two separate modules (SAMD51 + ESP32) are:
148

Ricardo Quesada's avatar
Ricardo Quesada committed
149
* You can see the console of both the ESP32 and SAM51 at the same time
150
151
* Faster flashing: it is > 2x faster to flash Bluepad32 directly to the ESP32 than
  to flash it with "PassThrough" method required for AirLift modules.
Ricardo Quesada's avatar
Ricardo Quesada committed
152
* If needed, you can inspect the SPI protocol with a logic analizer
153
154
155
156

[esp32-adafruit]: https://www.adafruit.com/product/4172?gclid=EAIaIQobChMI-eeixraV7QIVED2tBh2qywzJEAQYASABEgLsTfD_BwE
[amazon-esp32]: https://www.amazon.com/s?k=esp32+module+breakout
[feather_m4]: https://www.adafruit.com/product/3857