Alternativa open source inicial ao aplicativo M-EFCS da M-Vave (que oficialmente só possui versões para Android/iOS, Windows e macOS), permitindo controlar e inspecionar a pedaleira M-Vave MK-300 diretamente pelo terminal no Linux (ou qualquer sistema com suporte a Bluetooth LE via bleak).
Caution
EXPERIMENTAL PHASE: USE AT YOUR OWN RISK
This application and project are still under active development/testing (Beta). Communicating directly with the pedal's core memory structures via reverse-engineered protocols interacts intimately with the device's hardware. The author is not responsible for any bricked devices, hardware damage, or data loss. Use this software and the reverse-engineered protocols entirely at your own risk.
(Projeto em fase experimental e de engenharia reversa independente. Não possui vínculo oficial com a M-VAVE. Utilize por sua conta e risco).
A M-Vave MK-300 utiliza Bluetooth Low Energy (BLE) para comunicação em tempo real com o app oficial M-EFCS. Como não há cliente oficial para Linux, este projeto implementa a engenharia reversa do protocolo proprietário AE40 (leitura/escrita direta de memória de presets e parâmetros) e do BLE-MIDI, oferecendo uma ferramenta de linha de comando rápida e scriptável.
Desenvolvido e testado atualmente no Linux (Ubuntu 26.04.1 LTS) com firmware v070 da M-Vave MK-300.
- ✅ Conexão via Bluetooth LE (BLE) no Linux (testado no Ubuntu 26.04.1 LTS via BlueZ +
bleak) - ✅ Interface Web no Navegador (
index.html+mk300_web.py): funciona via Web Bluetooth API (direto no Chrome/Brave/Edge, inclusive pelo GitHub Pages) ou via Ponte Local (Bleak) em qualquer navegador! - ✅ Liberação automática da conexão BlueZ (evita que o ALSA BLE-MIDI trave o anúncio do pedal)
- ⏳ Conexão via cabo USB — em breve
- ✅ Inspeção do preset atual (
info): nome, número do slot, cor do LED, volume, BPM, Pan e ordem/estado da cadeia de sinal (Chain). - ✅ Leitura completa de parâmetros (
params): exibe o modelo selecionado (AMP,CAB,DS,FX,DLY,REV, etc.) e os 12 parâmetros de cada um dos 11 módulos. - ✅ Troca de presets (
preset,pc): via protocolo AE40 (todos os 160 slots:0a159) ou via BLE-MIDI Program Change (0a127). - ✅ Controle de módulos (
on,off,toggle): liga, desliga ou inverte qualquer um dos 11 módulos da cadeia (WAH,FX,GATE,DS,AMP,CAB,EQ,MOD,DLY,REV,VOL). - ✅ Edição de parâmetros em tempo real (
param,vol,bpm,pan): altera knobs pelo nome (ex.:gain,mix,time) ou pelo índice numérico (0a11). - ✅ Editor Web completo (
index.html): troca de modelo/tipo (effunit), reordenação da cadeia de sinal (Chain), edição de nome e cor do LED do preset, sliders em tempo real e importação/exportação de.bin(448 bytes). - ✅ Leitura de nomes da memória do pedal (
names,presets): extrai os nomes atuais dos 160 presets, 120 AMPs, 100 CABs e 40 DS diretamente da memória da pedaleira (incluindo IRs/AMPs importados pelo usuário) e salva em cache (mk300_names.json). - ✅ Backup binário de preset (
dump): salva os 448 bytes brutos do preset em edição em um arquivo.bin. - ✅ Encadeamento de comandos: executa várias ações em uma única conexão BLE.
- ⏳ Gravação permanente no slot (Save na Flash) — em breve
- ⏳ Mapeamento completo dos nomes de knobs de todos os subtipos de
FX,DLYeREV— em andamento
Nota: Assim como no app M-EFCS, alterações feitas no buffer de edição ficam ativas imediatamente no som (o botão
SAVEda pedaleira começa a piscar), mas só são gravadas permanentemente se você salvar no pedal.
- Python 3.9+
- BlueZ (
bluetoothctlinstalado e serviçobluetoothativo no Linux) - Biblioteca Python
bleak
git clone https://github.com/rafaelsupport/mk300ctl.git
cd mk300ctl
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtCom o Bluetooth da pedaleira piscando (segure o botão GLOB caso esteja desligado), rode o script de diagnóstico:
python3 tests/diag.pyEle listará os dispositivos BLE próximos. Caso o MAC da sua unidade seja diferente do padrão configurado em mk300ctl.py, você pode passá-lo via --mac XX:XX:XX:XX:XX:XX ou editar a constante MAC no topo do mk300ctl.py.
🌐 Acesse direto pelo navegador (GitHub Pages): https://rafaelsupport.github.io/mk300ctl/
Inspirada na ideia e abordagem do projeto mvave-blackbox-edit (de @jvsobrinho), a interface web (index.html) permite controlar a MK-300 visualmente pelo navegador com dois modos de conexão:
- Direto pelo Navegador (Web Bluetooth API / GitHub Pages):
Sem precisar instalar nada! Basta abrir https://rafaelsupport.github.io/mk300ctl/ no Chrome, Brave ou Edge (no Linux, ative
chrome://flags/#enable-experimental-web-platform-features) e clicar em "Conectar (Web Bluetooth)". - Via Ponte Local (
./mk300_web.py) — Recomendado no Linux: Funciona em qualquer navegador (Firefox, Chrome, Brave) e libera automaticamente a conexão ociosa do BlueZ/ALSA:./mk300_web.py # Abra http://127.0.0.1:8080 no navegador e clique em "Conectar via Ponte Local (Bleak)"
# Sincronizar nomes de presets, AMPs, CABs e DS da memória do pedal (recomendado rodar 1x)
./mk300ctl.py names
# Listar todos os 160 presets em cache
./mk300ctl.py presets
# Ver resumo do preset atual e cadeia de sinal
./mk300ctl.py info
# Ver todos os módulos, modelos selecionados e valores dos parâmetros (knobs)
./mk300ctl.py params
# Trocar de preset (0 a 159)
./mk300ctl.py preset 12
# Ligar / desligar / inverter módulos
./mk300ctl.py on DLY
./mk300ctl.py off FX
./mk300ctl.py toggle REV
# Alterar parâmetros de um módulo (por nome ou índice 0..11)
./mk300ctl.py param AMP gain 80
./mk300ctl.py param DLY mix 35
./mk300ctl.py param AMP 0 80
# Ajustes globais do preset
./mk300ctl.py vol 75
./mk300ctl.py bpm 120
./mk300ctl.py pan -20
# Executar vários comandos na mesma conexão Bluetooth
./mk300ctl.py preset 3 off DLY on FX param AMP gain 65 info
# Salvar dump binário do preset atual (448 bytes)
./mk300ctl.py dump meu_preset.bin| Opção | Descrição |
|---|---|
-v, --verbose |
Mostra o tráfego de pacotes BLE enviados/recebidos (TX/RX em hexadecimal) |
-q, --quiet |
Suprime mensagens de progresso no stderr e exibe apenas a saída final no stdout |
--debug |
Exibe o traceback completo em caso de erro |
--mac XX:..:XX |
Usa outro endereço MAC Bluetooth |
--timeout N |
Tempo máximo (em segundos) procurando o anúncio BLE do pedal (padrão: 10) |
A MK-300 expõe dois serviços principais via Bluetooth LE:
- Serviço Proprietário AE40 (
0000ae40-0000-1000-8000-00805f9b34fb):- Write (
0000ae41-...): envio de comandos para o pedal (Write Without Response). - Notify (
0000ae42-...): respostas e dados lidos da memória do pedal.
- Write (
- Serviço BLE-MIDI Padrão (
03b80e5a-ede8-4b33-a751-6ce34ec4c700):- Característica I/O (
7772e5db-3868-4112-a1a9-f2669d106bf3): recebe e envia mensagens MIDI padrão encapsuladas em BLE-MIDI (0x80 0x80 <status> <data...>).
- Característica I/O (
Todos os pacotes enviados e recebidos no serviço AE40 seguem o formato:
+------+------+------+-------------------+----------------+------+
| 0x00 | 0x59 | CMD | LEN (3 bytes LE) | PAYLOAD (N B) | CKS |
+------+------+------+-------------------+----------------+------+
- Cabeçalho fixo:
0x00 0x59 CMD:0x11: Handshake / identificação do modelo (retorna string"MK-300").0x22: Escrita em endereço de memória ([type:1B] [addr:4B LE] [size:3B LE] [dados...]).0x23: Leitura de endereço de memória ([type:1B] [addr:4B LE] [size:3B LE]).
CKS(Checksum de 1 byte): complemento de 1 da soma dos bytes doPAYLOAD:(~sum(payload)) & 0xFF.- Leituras grandes são fatiadas em blocos de até
1000bytes (o app oficial usa no máximo1015).
| Endereço Base | type |
Tamanho / Formato | Descrição |
|---|---|---|---|
0x10000000 |
0x04 |
448 bytes (TPatch) |
Buffer do preset em edição ao vivo |
0x20000000 |
0x04 |
2+ bytes |
Dados globais (byte[1] = índice 0..159 do preset atual) |
0xE0000000 + N |
0x04 |
Escrita [0x01] |
Troca imediatamente para o preset N (0..159) |
0x70200000 |
0x04 |
160 × 17 bytes |
Nomes salvos dos 160 presets (strings terminadas em \0) |
0x80000000 |
0x05 |
100 × 14 bytes |
Nomes dos 100 CABs na memória do pedal |
0x90000000 |
0x05 |
120 × 14 bytes |
Nomes dos 120 AMPs na memória do pedal |
0xA0000000 |
0x05 |
40 × 14 bytes |
Nomes dos 40 pedais de Drive/DS na memória do pedal |
| Offset | Tamanho | Tipo | Descrição |
|---|---|---|---|
0 (0x00) |
20 B | char[20] |
Nome do preset (terminado em \0) |
20 (0x14) |
4 B | uint32 LE |
Cor do LED em RGB (#RRGGBB) |
24 (0x18) |
2 B | uint16 LE |
Volume do preset (0..100) |
26 (0x1A) |
2 B | uint16 LE |
BPM (40..240) |
28 (0x1C) |
2 B | int16 LE |
Pan (-100..100) |
32 (0x20) |
11 B | uint8[11] |
Ordem dos 11 módulos na cadeia de sinal (0..10) |
43 (0x2B) |
11 B | uint8[11] |
Estado ON (1) / OFF (0) de cada módulo |
54 (0x36) |
11 B | uint8[11] |
Tipo/modelo selecionado (effunit) em cada módulo |
66 (0x42) |
264 B | int16 LE[11][12] |
12 parâmetros (int16) para cada um dos 11 módulos |
Os 11 módulos têm índices fixos nos arrays de estado/tipo/parâmetros:
0: WAH, 1: FX, 2: GATE, 3: DS, 4: AMP, 5: CAB, 6: EQ, 7: MOD, 8: DLY, 9: REV, 10: VOL.
Como a MK-300 também anuncia o serviço BLE-MIDI, o daemon bluetoothd (BlueZ) do Linux costuma reconectar sozinho à pedaleira para criar uma porta ALSA MIDI, fazendo a pedaleira parar de anunciar pacotes BLE e bloqueando novas conexões GATT. O mk300ctl.py detecta isso automaticamente via bluetoothctl e libera a conexão ociosa antes de iniciar a comunicação.
.
├── index.html # Interface Web (Web Bluetooth API + Ponte Local + Editor .bin offline)
├── mk300_web.py # Servidor HTTP local com ponte BLE via Bleak para o Linux
├── mk300ctl.py # CLI principal de controle da MK-300
├── mk300_catalog.py # Catálogo de efeitos, modelos de fábrica e nomes de parâmetros
├── mk300_names.json # Cache dos nomes de presets/AMP/CAB/DS lidos da pedaleira
├── requirements.txt # Dependências Python (bleak)
└── tests/ # Utilitários isolados para diagnóstico e engenharia reversa
├── diag.py # Scanner BLE e listagem de serviços/características GATT
├── ae40.py # Teste isolado de baixo nível do protocolo AE40 (handshake/read/write)
├── dump.py # Dump bruto de qualquer região de memória via AE40
├── bindiff.py # Compara dois dumps (.bin) byte a byte e int16 LE para mapear novos knobs
└── midi.py # Monitor e injetor de mensagens BLE-MIDI (Program Change / Control Change)
- Interface Web no navegador inspirada pelo projeto mvave-blackbox-edit de @jvsobrinho, que desenvolveu um editor Web Bluetooth similar para a pedaleira M-Vave Blackbox.