Add install/uninstall scripts and rewrite the README around them
install.sh sets up a private virtualenv, the udev rule (group picked automatically), and optionally a systemd user service (--service) and LAN access with a subnet-limited firewalld/ufw rule (--lan). It records what it changed so uninstall.sh can undo exactly that. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5.5
@@ -1,7 +1,7 @@
|
||||
# dgm20-linux
|
||||
|
||||
Control the **Maono DGM20** USB microphone on Linux. Maono Link only runs on Windows and macOS; this
|
||||
covers the same settings with a local web page and a command-line tool.
|
||||
Control the **Maono DGM20** USB microphone on Linux. Maono Link only runs on Windows and macOS;
|
||||
this covers the same settings with a local web page and a command-line tool.
|
||||
|
||||
|
||||
|
||||
@@ -12,59 +12,129 @@ covers the same settings with a local web page and a command-line tool.
|
||||
- RGB ring brightness
|
||||
- Factory reset
|
||||
|
||||
Pure Python 3.9+, no dependencies. Nothing leaves your machine: the page is served from localhost
|
||||
and loads no external fonts or scripts.
|
||||
Pure Python, no dependencies. Nothing leaves your machine: the page is served from your own
|
||||
computer and loads no external fonts or scripts.
|
||||
|
||||
> Unofficial. Not affiliated with or endorsed by Maono. Tested on a DGM20 with USB ID
|
||||
> `352f:0105`, firmware 2.1.2. Newer DGM20 revisions (`352f:0112`) and the DGM20G/DGM20W
|
||||
> use different firmware and are not supported yet.
|
||||
> Unofficial. Not affiliated with or endorsed by Maono.
|
||||
|
||||
## Supported hardware
|
||||
|
||||
| Model | USB ID | Status |
|
||||
|-------|--------|--------|
|
||||
| DGM20 | `352f:0105` | Supported, tested on firmware 2.1.2 |
|
||||
| DGM20 (newer revision) | `352f:0112` | Not yet |
|
||||
| DGM20G, DGM20W | `352f:0113`, `352f:041a`-`041d` | Not yet |
|
||||
|
||||
Find your mic's ID with `lsusb | grep -i maono`. If you have one of the unsupported models and want
|
||||
to help, open an issue with that output.
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
pipx install git+https://git.reiners.dev/ReinersCloudConsulting/dgm20-linux.git
|
||||
# or, from a checkout
|
||||
pipx install .
|
||||
```
|
||||
|
||||
Let your user reach the mic without root, then unplug and replug it:
|
||||
You need Python 3.9 or newer with `venv` (Debian and Ubuntu: `sudo apt install python3-venv`).
|
||||
|
||||
```sh
|
||||
sudo cp udev/70-maono-dgm20.rules /etc/udev/rules.d/
|
||||
sudo udevadm control --reload && sudo udevadm trigger
|
||||
git clone https://git.reiners.dev/ReinersCloudConsulting/dgm20-linux.git
|
||||
cd dgm20-linux
|
||||
./install.sh
|
||||
```
|
||||
|
||||
The rule grants access to the logged-in desktop user (`uaccess`) and to the `wheel` group, which
|
||||
covers ssh sessions. Change the group if your distro uses a different one.
|
||||
Then unplug the mic and plug it back in once.
|
||||
|
||||
The installer:
|
||||
|
||||
1. puts the program in its own virtualenv under `~/.local/share/dgm20-linux`, with the commands
|
||||
`dgm20ctl` and `dgm20-web` linked into `~/.local/bin`, and
|
||||
2. asks for sudo once to add a udev rule (`/etc/udev/rules.d/70-maono-dgm20.rules`) that lets you
|
||||
use the mic's control channel without root.
|
||||
|
||||
Run it as your normal user, not with sudo.
|
||||
|
||||
### Options
|
||||
|
||||
| Option | What it does |
|
||||
|--------|--------------|
|
||||
| `--service` | Runs the control page in the background now and every time you log in (systemd user service). |
|
||||
| `--lan` | Lets other devices on your network open the page too. Opens the port in firewalld or ufw for your local subnet only. Implies `--service`. |
|
||||
| `--port N` | Uses a different port (default 8720). |
|
||||
| `--group NAME` | Group allowed to use the mic from ssh sessions. Default: the first of `plugdev`, `wheel`, `sudo` that you belong to. Desktop logins always have access. |
|
||||
| `--no-udev` | Skips the udev rule. |
|
||||
| `--dry-run` | Prints every change instead of making it. |
|
||||
|
||||
`--lan` has no login. Anyone on your network can change your mic settings, so only use it on a
|
||||
network you trust. If you run a firewall other than firewalld or ufw, the installer tells you what
|
||||
to allow.
|
||||
|
||||
### Uninstall
|
||||
|
||||
```sh
|
||||
./uninstall.sh
|
||||
```
|
||||
|
||||
This removes everything the installer added: the service, firewall rule, udev rule and program
|
||||
files. The installer keeps a record of what it changed, so only those changes are undone. Your mic
|
||||
keeps its current settings.
|
||||
|
||||
## Use
|
||||
|
||||
```sh
|
||||
dgm20-web --open # control page at http://localhost:8720
|
||||
dgm20ctl # show settings
|
||||
dgm20ctl set nc on nc-level 80 enhance off
|
||||
dgm20ctl watch # print changes made on the mic itself
|
||||
dgm20-web --open # open the control page (http://localhost:8720)
|
||||
dgm20ctl # show current settings
|
||||
dgm20ctl set nc on nc-level 80
|
||||
dgm20ctl set monitor off enhance on brightness 40
|
||||
dgm20ctl watch # print changes made on the mic itself
|
||||
dgm20ctl info # model and firmware
|
||||
dgm20ctl factory-reset --yes
|
||||
```
|
||||
|
||||
To keep the page running in the background:
|
||||
| Setting | Values |
|
||||
|---------|--------|
|
||||
| `mute` | on, off |
|
||||
| `nc` | on, off: noise cancellation |
|
||||
| `nc-level` | 0-100: noise cancellation strength |
|
||||
| `enhance` | on, off: vocal enhancement |
|
||||
| `monitor` | on, off: hear yourself in headphones plugged into the mic |
|
||||
| `brightness` | 0-100: RGB ring |
|
||||
|
||||
```sh
|
||||
cp contrib/dgm20-web.service ~/.config/systemd/user/
|
||||
systemctl --user enable --now dgm20-web
|
||||
```
|
||||
|
||||
`dgm20-web` only listens on localhost. `--host 0.0.0.0` makes it reachable from your network, and
|
||||
anyone on that network can then change your mic settings, because there is no login.
|
||||
Settings are stored on the mic, so they stay the same after a replug and on other computers.
|
||||
|
||||
Input gain and headphone volume are standard USB audio controls. Set them in your desktop's sound
|
||||
settings, `pavucontrol` or `alsamixer`. The mic does not expose them on its control channel.
|
||||
settings, `pavucontrol` or `alsamixer`.
|
||||
|
||||
### Using the page from another computer without opening a port
|
||||
|
||||
If the mic is plugged into a machine you reach over ssh, forward the port instead of using `--lan`:
|
||||
|
||||
```sh
|
||||
ssh -L 8720:localhost:8720 that-machine
|
||||
```
|
||||
|
||||
Then open http://localhost:8720 on your own computer.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"no permission to open /dev/hidrawN"**: the udev rule isn't applied yet. Unplug and replug the
|
||||
mic. Over ssh, make sure you're in the group the installer printed (`id -nG`). If you were just
|
||||
added to that group, log in again.
|
||||
|
||||
**"DGM20 (352f:0105) not found"**: check `lsusb | grep -i maono`. A different USB ID means a
|
||||
model that isn't supported yet (see above).
|
||||
|
||||
**The page says "Mic not found"**: plug the mic in. The page reconnects by itself.
|
||||
|
||||
**`dgm20-web: cannot listen on 127.0.0.1:8720`**: it's already running, for example as the
|
||||
service. Open http://localhost:8720, or pick another port with `--port`.
|
||||
|
||||
**Commands not found after installing**: `~/.local/bin` isn't on your `PATH`. Add
|
||||
`export PATH="$HOME/.local/bin:$PATH"` to your shell profile.
|
||||
|
||||
**Service stops when you log out**: run `sudo loginctl enable-linger $USER`.
|
||||
|
||||
## How it works
|
||||
|
||||
The settings were found by reading Maono Link's DGM20 plugin. See [PROTOCOL.md](PROTOCOL.md) for
|
||||
the packet format and register map. `dgm20ctl raw` gives direct register access if you want to
|
||||
explore.
|
||||
The mic has a vendor HID channel next to its audio interfaces. The settings were found by reading
|
||||
Maono Link's DGM20 plugin and then checked against a real mic. [PROTOCOL.md](PROTOCOL.md) documents
|
||||
the packet format and register map. `dgm20ctl raw get|set|dump` gives direct register access for
|
||||
exploring.
|
||||
|
||||
## Development
|
||||
|
||||
|
||||
Reference in New Issue
Block a user