Skip to content

Commit dca73e2

Browse files
APIUMAPIUM
committed
Add github action
1 parent 3330564 commit dca73e2

File tree

2 files changed

+166
-56
lines changed

2 files changed

+166
-56
lines changed

‎.github/workflows/build.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Build Firmware
2+
3+
on:
4+
push:
5+
branches: [master]
6+
release:
7+
types: [published]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v4
16+
17+
- name: Build Docker image
18+
run: docker build -t something-remote-build .
19+
20+
- name: Build firmware
21+
run: |
22+
docker run --rm -v "$PWD:/project" -w /project something-remote-build \
23+
make build BOARD=EVERYTHING_REMOTE
24+
25+
- name: Merge firmware bins
26+
run: |
27+
pip install esptool
28+
esptool.py --chip esp32 merge_bin -o something-remote-firmware.bin \
29+
--flash_mode dio --flash_size 4MB \
30+
0x1000 build/bootloader.bin \
31+
0x8000 build/partition-table.bin \
32+
0x10000 build/micropython.bin
33+
34+
- name: Upload artifact
35+
uses: actions/upload-artifact@v4
36+
with:
37+
name: something-remote-firmware
38+
path: something-remote-firmware.bin
39+
40+
- name: Attach to release
41+
if: github.event_name == 'release'
42+
uses: softprops/action-gh-release@v1
43+
with:
44+
files: something-remote-firmware.bin

‎README.md‎

Lines changed: 122 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,159 @@
1-
# Shield Remote
1+
# Something Remote
22

3-
BLE HID remote control for Nvidia Shield using M5Stack Atom Echo and MicroPython.
3+
BLE HID remote control for Nvidia Shield with Home Assistant integration, using the Everything Remote ESP32 board.
44

55
## Hardware
66

7-
- M5Stack Atom Echo (ESP32-PICO-D4)
8-
- Button: GPIO39 (top button)
9-
- LED: GPIO27 (SK6812 NeoPixel)
7+
- Everything Remote v1 board (ESP32 with 21 buttons)
8+
- MPU6050 accelerometer for motion wake (optional)
9+
- SDA: GPIO33, SCL: GPIO22, INT: GPIO36 (VP)
1010

1111
## Features
1212

13-
- BLE HID Keyboard profile
14-
- Press button to send Right Arrow key
15-
- LED status: Blue=advertising, Green=connected, White=key pressed
16-
- Bonding keys stored in ESP32 NVS
13+
- **BLE HID** - Keyboard and Consumer Control for Shield navigation
14+
- **Home Assistant** - MQTT integration with auto-discovery
15+
- **Power Management** - Light sleep and deep sleep with motion wake
16+
- **Captive Portal** - WiFi/MQTT setup via browser
1717

18-
## Prerequisites
18+
## Quick Start - Flashing Pre-built Firmware
1919

20-
- Docker
20+
### Download
2121

22-
## Build (Docker)
22+
Get `something-remote-firmware.bin` from [Releases](../../releases/latest).
2323

24-
### 1. Build Docker Image (first time only)
24+
### Flash
2525

26-
```bash
27-
make docker-build
28-
```
26+
1. **Connect** board via USB and find the port:
27+
- Linux: `/dev/ttyUSB0`
28+
- Mac: `/dev/cu.usbserial-*`
29+
- Windows: `COM3` (check Device Manager)
2930

30-
### 2. Build Firmware
31+
2. **Erase and flash**:
32+
```bash
33+
# Using uv (recommended - no install needed)
34+
uvx esptool --port /dev/ttyUSB0 erase_flash
35+
uvx esptool --port /dev/ttyUSB0 write_flash 0x0 something-remote-firmware.bin
3136

32-
```bash
33-
make build
34-
```
37+
# Or using pip
38+
pip install esptool
39+
esptool.py --port /dev/ttyUSB0 erase_flash
40+
esptool.py --port /dev/ttyUSB0 write_flash 0x0 something-remote-firmware.bin
41+
```
3542

36-
### 3. Copy Firmware to Local Directory
43+
3. **Configure**: Connect to "SomethingRemote-Setup" WiFi (password: `12345678`), enter your WiFi and MQTT settings
3744

38-
```bash
39-
make copy-firmware
40-
```
45+
4. **Pair**: See [Pairing with Shield](#pairing-with-shield) below
4146

42-
### 4. Flash to Device
47+
## LED Status
4348

44-
Connect Atom Echo via USB, then:
49+
| Color | State |
50+
|-------|-------|
51+
| Blue | Advertising (ready to pair) |
52+
| Green | Connected to Shield |
53+
| White | Button pressed |
54+
| Purple | Home Assistant activity |
55+
| Yellow | Setup portal active |
56+
| Red | Error or BLE forget |
4557

46-
```bash
47-
make flash PORT=/dev/ttyUSB0
48-
```
58+
## Button Combos
4959

50-
Or flash manually with esptool:
60+
| Combo | Hold Time | Action |
61+
|-------|-----------|--------|
62+
| **Power + Back** | 5 seconds | Clear BLE bonds, restart advertising (for pairing) |
63+
| **Shortcut1 + Shortcut3** | 5 seconds | Enter WiFi/MQTT setup portal |
5164

52-
```bash
53-
pip install esptool
54-
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z 0x1000 build/firmware.bin
55-
```
65+
## Button Mapping
5666

57-
### Interactive Shell
67+
### BLE HID (Shield Control)
68+
- D-pad: Up/Down/Left/Right arrows
69+
- Select: Enter
70+
- Back: Consumer Control Back (AC Back)
71+
- Home: Consumer Control Home (AC Home)
72+
- Play/Pause, Vol+, Vol-, Mute: Consumer Control media keys
73+
- Ch+/Ch-: Page Up/Down
5874

59-
To debug or explore the build environment:
75+
### Home Assistant (MQTT)
76+
- Power: `power` action
77+
- Shortcuts 1-4: `shortcut_1` to `shortcut_4` actions
78+
- Brightness +/-: `brightness_up`/`brightness_down` actions
6079

61-
```bash
62-
make shell
63-
```
80+
## Setup
6481

65-
## Usage
82+
### First Time Setup
6683

67-
1. After flashing, device starts advertising (blue LED)
68-
2. On Nvidia Shield: Settings → Remote & Accessories → Add Accessory
69-
3. Select "Shield Remote"
70-
4. Once connected (green LED), press button to navigate right
71-
5. LED flashes white on button press
84+
1. Flash firmware (see Build section)
85+
2. Device creates WiFi AP: "Something Remote Setup"
86+
3. Connect to AP, browser opens setup page
87+
4. Enter WiFi credentials and MQTT broker details
88+
5. Device restarts and connects
7289

73-
## Troubleshooting
90+
### Pairing with Shield
91+
92+
1. Ensure LED is **blue** (advertising)
93+
2. If not blue, hold **Power + Back** for 5 seconds
94+
3. On Shield: Settings → Remote & Accessories → Add Accessory
95+
4. Select "Something Remote"
96+
5. LED turns **green** when connected
97+
98+
### Re-entering Setup
7499

75-
- If Shield won't pair, ensure location services are enabled on Shield
76-
- Use `screen /dev/ttyUSB0 115200` to view debug output
77-
- Check BLE advertising with nRF Connect app on phone
100+
Hold **Shortcut1 + Shortcut3** for 5 seconds. LED turns yellow.
101+
102+
## Power Management
103+
104+
- **1 minute** idle → Light sleep (BLE stays active)
105+
- **5 minutes** of light sleep → Deep sleep
106+
- **Wake**: Any button press or motion (if MPU6050 installed)
107+
108+
## Build
109+
110+
### Prerequisites
111+
112+
```bash
113+
# ESP-IDF v5.2.x
114+
cd ~
115+
git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git
116+
cd esp-idf && ./install.sh esp32 && source export.sh
117+
118+
# MicroPython
119+
cd ~
120+
git clone https://github.com/micropython/micropython.git
121+
cd micropython && git checkout v1.24.1 && git submodule update --init
122+
make -C mpy-cross
123+
```
124+
125+
### Build & Flash
126+
127+
```bash
128+
./build.sh
129+
./flash.sh /dev/ttyUSB0
130+
```
78131

79132
## Project Structure
80133

81134
```
82-
├── board/ATOM_ECHO/ # MicroPython board definition
83-
├── modules/ # Python code (frozen into firmware)
84-
│ ├── hid_services.py # BLE HID implementation
85-
│ ├── shield_remote.py # Main application
86-
│ └── main.py # Entry point
87-
├── build.sh # Build script
88-
└── flash.sh # Flash script
135+
├── board/ATOM_ECHO/ # MicroPython board definition
136+
├── modules/ # Python code (frozen into firmware)
137+
│ ├── shield_remote.py # Main application
138+
│ ├── hid_services.py # BLE HID implementation
139+
│ ├── hid_keystores.py # BLE bonding key storage
140+
│ ├── ha_client.py # Home Assistant MQTT client
141+
│ ├── wifi_setup.py # Captive portal for setup
142+
│ ├── config.py # Configuration storage
143+
│ ├── mpu6050_wake.py # Accelerometer motion wake
144+
│ ├── logger.py # File-based logging
145+
│ └── main.py # Entry point
146+
├── build.sh # Build script
147+
└── flash.sh # Flash script
89148
```
90149

150+
## Troubleshooting
151+
152+
- **Can't pair**: Hold Power + Back 5 sec to clear bonds, then retry
153+
- **Can't see in Shield menu**: Check LED is blue, try nRF Connect app to verify advertising
154+
- **WiFi issues**: Hold Shortcut1 + Shortcut3 5 sec to re-enter setup
155+
- **Debug output**: `screen /dev/ttyUSB0 115200`
156+
91157
## License
92158

93159
BLE HID library adapted from MicroPythonBLEHID (GPL-3.0).

0 commit comments

Comments
 (0)