{"id":18753630,"url":"https://github.com/adzierzanowski/volcano","last_synced_at":"2025-04-13T00:31:50.180Z","repository":{"id":37436664,"uuid":"497846517","full_name":"adzierzanowski/volcano","owner":"adzierzanowski","description":"libusb-based driver for Modecom Volcano Lanparty RGB keyboard","archived":false,"fork":false,"pushed_at":"2023-08-05T00:17:14.000Z","size":197,"stargazers_count":5,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T18:57:25.229Z","etag":null,"topics":["driver","keyboard","lanparty","macos","modecom","rgb","volcano"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adzierzanowski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-30T08:04:37.000Z","updated_at":"2024-11-30T13:20:41.000Z","dependencies_parsed_at":"2024-11-07T17:48:46.104Z","dependency_job_id":null,"html_url":"https://github.com/adzierzanowski/volcano","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzierzanowski%2Fvolcano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzierzanowski%2Fvolcano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzierzanowski%2Fvolcano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzierzanowski%2Fvolcano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adzierzanowski","download_url":"https://codeload.github.com/adzierzanowski/volcano/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650590,"owners_count":21139670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["driver","keyboard","lanparty","macos","modecom","rgb","volcano"],"created_at":"2024-11-07T17:26:27.810Z","updated_at":"2025-04-13T00:31:49.402Z","avatar_url":"https://github.com/adzierzanowski.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Modecom Volcano Lanparty RGB keyboard UNIX userland driver\n\nThis is a driver for the Modecom Volcano Lanparty RGB keyboard. I made it\nbecause the only available drivers are made for Windows.\n\nThe driver also works on Linux (tested on Kubuntu 20.04).\n\nIt operates in the userland so the only requirement is to have `sudo`\npermissions.\n\nThe driver consists of:\n\n* The keyboard handling library: `src/keyboard.h`\n* The CLI frontend: `src/main.c` -\u003e `volcano`\n* The daemon which is capable of listening to the hotplug events: `src/daemon.c` -\u003e `volcanod`\n* The web control panel for communicating with the daemon: `src/srv.c` -\u003e `volcanosrv`\n\nThe daemon and the web panel are of course optional and you can control the\nkeyboard using just the main binary `volcano`. Nevertheless, the daemon is\na little bit more powerful and easier to use.\n\n#### Screenshot of the web control panel\n\n![](https://i.imgur.com/cwjAgDg.png)\n\n**Table of contents**\n\n- [Modecom Volcano Lanparty RGB keyboard UNIX userland driver](#modecom-volcano-lanparty-rgb-keyboard-unix-userland-driver)\n      - [Screenshot of the web control panel](#screenshot-of-the-web-control-panel)\n- [Building](#building)\n  - [macOS](#macos)\n  - [Ubuntu](#ubuntu)\n  - [Tools](#tools)\n- [Creating keymaps](#creating-keymaps)\n- [Daemon](#daemon)\n  - [Installation](#installation)\n    - [Build](#build)\n    - [Configuration file](#configuration-file)\n    - [Installing the daemon: macOS launchctl](#installing-the-daemon-macos-launchctl)\n    - [Installing the daemon: Linux](#installing-the-daemon-linux)\n  - [Daemon Socket Commands](#daemon-socket-commands)\n- [Main executable usage](#main-executable-usage)\n- [Development](#development)\n  - [Dependecies](#dependecies)\n  - [Development status](#development-status)\n    - [Implemented things](#implemented-things)\n    - [In progress](#in-progress)\n  - [Other files](#other-files)\n  - [Contributing](#contributing)\n\n# Building\n\n## macOS\n\nInstall `libusb` 1.0. For example:\n\n```bash\n$ brew install libusb\n```\n\nIf you've installed `libusb` in another way, you might need to modify the\n`Makefile` to link against this library.\n\n\nFinally run `make`:\n\n```bash\n$ make\n```\n\n## Ubuntu\n\nInstall `libusb` 1.0.\n\n```bash\n$ sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev\n```\n\nRun `make`:\n\n```bash\n$ make\n```\n\n## Tools\n\nIf you wish to use included tools, you'll need `python3` and install the\nrequirements:\n\n```bash\n$ python3 -m pip install -r requirements.txt\n```\n\n\n# Creating keymaps\n\nYou can easily create keyboard mappings through the web control panel of the\ndaemon.\n\nAnother way to create a keymapping is to convert a YAML file to binary file and\nthen load it using `volcano` or `volcanod` (see *Daemon* section).\n\n```bash\n$ python3 tools/mkmap.py sample-keymap.yml kmap.dat\n$ sudo volcano -M kmap.dat\n```\n\n# Daemon\n\nTo make the driver's work seamless it's best to use the daemon which listens\nfor commands in background and reacts to hotplugging of the keyboard.\n\n## Installation\n\n### Build\n\nClone the repository and build it:\n\n```bash\n$ git clone https://github.com/adzierzanowski/volcano.git /Users/user/volcano\n$ cd /Users/user/volcano\n$ make\n```\n\nThe resulting executables will be created in the `./bin` folder:\n* `volcano` - CLI for controlling the keyboard without the daemon running\n* `volcanod` - the daemon executable\n* `volcanosrv` - the web control panel server communicating with the daemon\n* `volcanoctl` - a shell script which opens the control panel (assuming it uses the default port `65226`)\n\n### Configuration file\n\nCreate `.volcanorc` file with basic configuration:\n\n```conf\nLOG_LEVEL=1\nLOG_COLOR=0\nSOCKET_FILE=/Users/user/.volcano.sock\nSOCKET_UID=501\nSOCKET_GID=20\nKMAP_FILE=/Users/user/kmap.dat\nINIT_MODE=ripple\nINIT_COLOR=00ffff\nSRV_ENABLE=1\nSRV_PORT=65226\nSRV_DATA=/Users/user/volcano/www\nSRV_EXE=/Users/user/volcano/bin/volcanosrv\n```\n\n| Key           | Description                                                  | Default                         |\n|---------------|--------------------------------------------------------------|---------------------------------|\n| `LOG_LEVEL`   | Logging verbosity (`0`=ERROR, `1`=WARN, `2`=INFO, `3`=DEBUG, `4`=SILLY) | `3`                  |\n| `LOG_COLOR`   | Boolean flag. If set, the logs are colored with ANSI codes   | `0`                             |\n| `SOCKET_FILE` | Socket file path for inter-process communication             | `$HOME/.volcano.sock`           |\n| `SOCKET_UID`  | Socket owner user ID (should be you)                         | `501` on macOS, `1000` on Linux |\n| `SOCKET_GID`  | Socket owner group ID                                        | `20` on macOS, `1000` on Linux  |\n| `KMAP_FILE`   | Keymap file loaded on keyboard hotplug                       | None                            |\n| `INIT_MODE`   | Initial color scheme after plugging                          | `norm`                          |\n| `INIT_COLOR`  | Initial color                                                | `0xffffff`                      |\n| `SRV_ENABLE`  | Enable locally hosted www control panel                      | `1`                             |\n| `SRV_PORT`    | Port at which the control panel is server                    | `65226`                         |\n| `SRV_DATA`    | Path to the control panel assets                             | `$BINPATH/www`*                 |\n\n\\* The path of the running executable\n\n### Installing the daemon: macOS launchctl\n\nNext, create `volcanod.plist` file in `/Library/LaunchDaemons` folder:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n  \u003ckey\u003eLabel\u003c/key\u003e\n  \u003cstring\u003evolcanod\u003c/string\u003e\n  \u003ckey\u003eProgramArguments\u003c/key\u003e\n  \u003carray\u003e\n    \u003cstring\u003e\u003c!--PATH TO VOLCANOD EXECUTABLE--\u003e\u003c/string\u003e\n    \u003cstring\u003e\u003c!--PATH TO .VOLCANORC FILE--\u003e\u003c/string\u003e\n  \u003c/array\u003e\n  \u003ckey\u003eKeepAlive\u003c/key\u003e\n  \u003ctrue /\u003e\n  \u003ckey\u003eStandardOutPath\u003c/key\u003e\n  \u003cstring\u003e/var/log/volcanod.log\u003c/string\u003e\n  \u003ckey\u003eStandardErrorPath\u003c/key\u003e\n  \u003cstring\u003e/var/log/volcanod.log\u003c/string\u003e\n  \u003ckey\u003eDebug\u003c/key\u003e\n  \u003ctrue /\u003e\n  \u003ckey\u003eRunAtLoad\u003c/key\u003e\n  \u003ctrue /\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\nTo enable the daemon\n\n```bash\n$ sudo launchctl load /Library/LaunchDaemons/volcanod.plist\n```\n\nTo disable\n\n```bash\n$ sudo launchctl unload /Library/LaunchDaemons/volcanod.plist\n```\n\n### Installing the daemon: Linux\n\nWell, you'll have to find out how to install daemons on Linux yourself.\n\n## Daemon Socket Commands\n\n| Command                  | Description         | Argument range                                                      |\n|--------------------------|---------------------|---------------------------------------------------------------------|\n| `kmap KMAP[172]`         | map keys            | 172 numbers from 0 to 255                                           |\n| `fkmap [FILE]`           | map keys            | a kmap file path                                                    |\n| `mode MODE`              | set color mode      | mode name, see `volcano -m list`                                    |\n| `color [R [G [B]]]`      | set color           | 0 \u003c= `R`, `G`, `B` \u003c= 255                                           |\n| `kcolor KEY [R [G [B]]]` | set color           | KEY - see `sample-kmap.yml` for reference, 0 \u003c= `R`, `G`, `B` \u003c 256 |\n| `speed LEVEL`            | animation speed     | 0 \u003c= `LEVEL` \u003c= 4                                                   |\n| `brightness LEVEL`       | brightness level    | 0 \u003c= `LEVEL` \u003c= 4                                                   |\n| `dir DIR`                | animation direction | 0 \u003c= `DIR` \u003c= 1                                                     |\n| `rate RATE`              | USB report rate     | `RATE` in (125, 250, 500, 1000)                                     |\n\nYou can test these commands with, for example, `socat`:\n\n```bash\n$ brew install socat\n$ echo mode matrix | socat - UNIX-CONNECT:/Users/user/.volcano.sock\nVLC_OK\n```\n\n# Main executable usage\n\n```\nOPTIONS:\n    -B (0-4)       set brightness (0-4)\n    -D (0-1)       set direction (0-1)\n    -S (0-4)       set speed\n    -R (0-1)       set rainbow\n    -H (0-3)       set report rate (0-3; 125 Hz - 1000 Hz)\n\n    -m MODE        select color mode ('list' to list all modes)\n    -M FILE        remap keyboard keys\n    -c             set color for entire keyboard\n    -C CMD         pass a command\n    -h             show this help message and exit\n    -k KEY         select a key for the color change\n    -r (0-255)     red value\n    -g (0-255)     green value\n    -b (0-255)     blue value\n\nEXAMPLES:\n    volcano -k BACKSPACE -r 255 -g 0 -b 0      # set backspace to red\n    volcano -c -g 255              # set the entire keyboard to green\n    volcano -C clear                      # clear the entire keyboard\n    volcano -C clear-m1    # clear the entire keyboard in custom mode\n```\n\n# Development\n\n## Dependecies\n\n* libusb 1.0\n* pyyaml\n\n## Development status\n\nIt's almost complete.\n\nSome refactoring is certainly needed.\n\nTo sniff USB communication between the keyboard and the original driver I used\n[Device Monitoring Studio](https://www.hhdsoftware.com/device-monitoring-studio).\n\n### Implemented things\n\n* setting single keys to a specified color in \"Custom\" mode\n* setting the whole keyboard color in supported modes\n* clearing the whole keyboard\n* switching between color schemes\n* self-hosted driver control panel\n* key mappings\n* setting the gradient in one of the color modes\n* updating settings on PnP\n\n### In progress\n\n* macros (on branch macros)\n\n## Other files\n\nThe repository contains `pck` folder which contains the packets sniffed during\nthe development. It's not needed for the driver to run properly. Some dev tools\nin `tools` folder use it, though.\n\n`map` folder contains packets which represents key mapping. These are in\nplain ASCII hexadecimal format.\n\n## Contributing\n\nPlease make a pull request if you've managed to get a grip of the commands.\nI'll be grateful.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzierzanowski%2Fvolcano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadzierzanowski%2Fvolcano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzierzanowski%2Fvolcano/lists"}