A macOS controller app for the Gecho Loopsynth v1 synthesiser by Mario at Gechologic. Built with SwiftUI, this app provides a full serial interface to the Gecho over USB, including MIDI keyboard integration for real-time note playing and chord building.

• macOS 26.3 or later
• Xcode 26.3 or later (to build from source)
• Gecho Loopsynth v1 hardware
• Gecho firmware v0.244 (other versions may work but are untested)
• CH340G USB driver (usually installs automatically on macOS
• Optional: any USB or Bluetooth MIDI keyboard for live play and chord input

• Serial connection via USB to the Gecho Loopsynth v1
• Console displaying all TX and RX messages in real time
• Direct command entry — type any TX command directly
• Physical button simulation — buttons 1, 2, 3, 4, SET and RST
• Channel selector — enter any channel number and send directly
• Song input — enter and send chord progressions in Gecho notation
• Melody input — enter and send melody strings in Gecho notation
• Query and Clear — query or clear stored Song and Melody from memory
• MIDI input — select any connected MIDI device as input source
• Live Play (channel #113) — play the Gecho toy box sampler in real time from a MIDI keyboard
• MIDI to Text Field — route MIDI keyboard input directly into the Song or Melody text fields
• Chord Builder — add notes one at a time from a MIDI keyboard to build chords, then send to Song
• MIDI console — displays all incoming MIDI messages

1. Clone this repository
2. Open GechoController.xcodeproj in Xcode
3. In Signing & Capabilities, set your own Development Team
4. Make sure App Sandbox has USB enabled under Hardware, or remove the sandbox entirely for personal use
5. Press Cmd + R to build and run

1. Connect your Gecho Loopsynth v1 via USB
2. Ensure the sliding switch is in the ON position
3. The RDY (Ready) LED should be blinking on the synth
4. Open GechoController and select the port from the dropdown — it will appear as something like cu.usbserial-XXXX or cu.wchusbserial-XXXX
5. Click Connect
6. If successful, the console will display the handshake response Hi there! followed by the firmware version
7. If connection fails, the console will display [Error] Handshake Failed. Check connection! followed by [Disconnected]

The Gecho v1 uses a CH340G USB-to-serial chip. On most modern macOS versions the driver installs automatically. If the port does not appear in the dropdown, install the driver manually from the official WCH source:

https://www.wch-ic.com/downloads/CH341SER_MAC_ZIP.html

After installing, unplug and replug the Gecho and the port should appear.

The four numbered buttons (1–4), SET and RST simulate pressing the physical buttons on the Gecho board. Note: button commands are only processed by the Gecho when it is in the idle state. During playback, the Gecho's audio loop only reads physical GPIO pins and ignores all serial button commands. Always use the physical buttons on the board during active playback.

Enter any valid channel number in the Channel field and press Send to activate that channel. See the Channel List section below for all available channels.

Enter a chord progression in the Song field using Gecho notation (see Note & Chord Format below). Enter a melody string in the Melody field.

Important — always send Song before Melody. Sending a SONG= command automatically clears the stored melody. This is hardcoded in the firmware. Always send Song first, then Melody.

• Send Song — sends SONG= followed by the Song field content, then automatically sends MELODY= if the Melody field is populated, then sends CHAN=111 to begin playback
• Query Song — queries the stored song from the Gecho's EEPROM. The board replies then auto-resets. The app reconnects automatically and populates the Song field
• Clear Song — clears both the stored Song and Melody from EEPROM, then resets the board
• Send Melody — sends MELODY= followed by the Melody field content
• Query Melody — queries the stored melody from EEPROM. The board auto-resets after replying
• Clear Melody — clears only the stored melody, leaving the song intact

Select your MIDI device from the Source dropdown. Press the refresh button if your device is not listed.

Live Play (Ch 113) — when ticked, automatically selects channel #113 and routes all incoming MIDI note-on events to the Gecho as FREQ= commands, playing the toy box sampler in real time.

MIDI to Text Fields — when ticked, incoming MIDI notes are converted to Gecho note notation and appended to whichever text field (Song or Melody) is currently in focus.

1. Ensure MIDI to Text Fields is unticked
2. Play notes one at a time on your MIDI keyboard — each note is shown in the Last note display
3. Click Add to Chord to add each note to the current chord being built
4. Once you have your chord (typically 3 notes), click Send Chord to Song to append it to the Song field
5. Click Clear Chord to start a new chord

All notes are written in plain text using the following format:

Available note letters: a b c d e f g (lowercase only)

Sharps only — no flats. Use enharmonic equivalents:

Song:

a3c4e4,e3g#3b3,d3f3a3,b3d4f4

Melody:

a4,c5,b4,g#4,a4,f4,d5,e5

All commands are plain text terminated with \n at 115200 baud.

⚠️ BTN= commands are ignored during playback. The Gecho audio loop only reads physical GPIO pins. Only BTN=RST works during channel #113.

⚠️ Always send SONG= before MELODY= — sending SONG= after MELODY= will wipe the melody.

MIDI to Hz formula: frequency = 440.0 × 2^((midiNote − 69) / 12)

⚠️ SAVE=, LOAD=, ERASE=ALL and MAP? all cause an automatic board reset after executing.

A selection of useful channels. Enter these in the Channel field and press Send.

For the full channel list refer to the Gecho v1 Manual.

• The Gecho v1 uses an STM32F405 microcontroller
• USB connection is via a CH340G USB-to-serial chip
• Serial communication is plain text at 115200 baud
• Persistent storage uses onboard EEPROM/flash memory
• EEPROM backup (via BAT+3V pad) requires your battery pack to be connected to the BAT+3V pad on the board to survive power-off. Flash storage via SAVE= is unconditionally persistent.
• The MIDI hardware extension (optocoupler + resistors solderable on the v1 board) enables channels such as #34 for direct MIDI-in from hardware. See gechologic.com/diy-midi-extension for the build guide.

Copyright © 2026 John McMillan

This app is released under the MIT License. See LICENSE for details.

The Gecho Loopsynth v1 firmware is also MIT licensed. Copyright © 2019 Mario / Gechologic.

This app is provided as-is, with no support, warranty, or guarantee of any kind.

• This is an independent community project and is not officially supported. No technical support, bug fixes, or updates are promised or implied.
• The author accepts no responsibility or liability for any damage, malfunction, data loss, or harm to your Gecho Loopsynth hardware or any other equipment, howsoever caused, arising from the use or misuse of this app.
• Use of this app is entirely at your own risk. You are responsible for ensuring that any commands sent to your Gecho Loopsynth are appropriate for your hardware and firmware version.
• This app communicates directly with your hardware over a serial connection. Incorrect or unexpected commands could affect the state of your device. Always ensure your Gecho firmware is up to date and that you understand the commands being sent before using them.

By downloading, building, or using this app you agree to these terms.

• Gecho Loopsynth v1 hardware and firmware by Mario at Gechologic
• Firmware source: github.com/h3o/Gecho_v1
• Serial command reference derived from analysis of the v1 firmware source code
• App built with Xcode, Swift and SwiftUI

This repository is not open to pull requests or contributions. The code is shared publicly for personal use and reference only.

You are welcome to fork this repository and do your own thing with it under the terms of the MIT license — just keep the copyright notice intact as required.

Please do not submit pull requests, issues, or feature requests as they will not be actioned.

This app is an independent community project and is not affiliated with or endorsed by Gechologic.