# Putting an FM-1 firmware on The Firmware Hub – instructions for an AI assistant You are helping a firmware maker list their M-VAVE FM-1 (or SMK-37) firmware on **The Firmware Hub** (https://thefirmwarehub.com) and keep its card up to date. The maker may not be a programmer. Do the work for them where you can, explain each step in plain words, and check everything against the rules below before they push. ## 1. What the hub needs before it lists a firmware All six are required: 1. **Open source.** GPL-3.0, MPL-2.0 or another open licence, with the complete source public in the GitHub repository (a zip of the source is not enough). A `LICENSE` file in the repository root. 2. **A release on GitHub** with the firmware package (`.fwsc`) attached as a release asset. The hub picks up every new release by itself within three hours. A version with *beta*, *alpha*, *rc* or a 0.x number gets a beta tag. 3. **Its own identity:** an `FM-1_` product name no other firmware uses. Check it at https://thefirmwarehub.com/submit/#check. Do not keep the number of the firmware it started from (Felucca's `FM-1_900` / `FM-1_980` …). Long numbers with a part of your own are safest, e.g. `FM-1_47` + version digits. 4. **The update loader** in the package, so players can install another firmware afterwards: https://thefirmwarehub.com/kb/#loader 5. **Tested on a real FM-1:** installed from the stock V15 firmware and from another firmware, and from this firmware another one installs again. Untested firmwares are not listed. If it cannot read other firmwares' projects or samples, the README says so. 6. **An `fmhub.json`** in the repository root, on the default branch (section 2). **No file, no listing.** ## 2. fmhub.json – the card, written by the maker The hub reads this file every three hours and puts it on the firmware's card by itself, no mail, no approval. Changing the card later = editing this file and pushing. ```json { "what": "A six-track groovebox: TR drums, a sampler with a mic input, a step sequencer and song mode.", "author": "Your Name", "kinds": ["groove"], "play": "https://you.github.io/yourfirmware/play/", "editor": "https://you.github.io/yourfirmware/editor/", "cheat": "https://you.github.io/yourfirmware/cheatsheet.pdf", "image": "docs/card.png", "color": "#FF7A00", "sounds": "own" } ``` Only these nine fields (and `smk37`, below) are allowed – any other field makes the whole file unused. A new firmware needs at least `what`, `kinds` and `image`, and **`sounds`** when it carries any sounds. | Field | Rule | |---|---| | `what` | The card's text. **English**, plain words: no HTML, no code, no links or web addresses (no `example.com`). At least 20 characters; more than 300 are cut at a word, so aim for 150–280. Say what it is and what you can do with it, for this version – not plans. **No advertising** (prices, discounts, "buy", sponsors, donation links) and **nothing hostile against anyone** – such a text is refused. | | `author` | The maker's name as the card shows it under the title (without it: the name the hub wrote down at listing). Plain text, 2–60 characters, no links or web addresses, nothing hostile. | | `kinds` | A list with one of `synth`, `groove` (groovebox), `drums` (drums and samplers), `chords`, `tracker`, `other`. If several are given, only the first counts. Pick the one people would look under. | | `play` | `https://` address of the firmware running in a browser (an emulator), if there is one. | | `editor` | `https://` address of a web editor for its sounds or settings, if there is one. | | `cheat` | `https://` address of a cheat sheet: a web page or a PDF (e.g. on GitHub Pages). | | `image` | The card's picture: a **path inside the repository** (not a URL), e.g. `docs/card.png`. See section 3. | | `sounds` | **Required when the firmware carries sounds** – none at all: leave it out, or `""`. Where every sample, sample bank, sound bank, ROM and recording the firmware carries comes from – in the repository and inside the package, also when converted to C arrays. Exactly one of: `""` or `"none"` (everything is made in code, optionally `"none – all synthesised"`), `"own"` or `"own: "` (made or recorded by the maker), `"CC0: "`, `"public domain: "`, `"licensed: , "` (someone else's, under a licence that allows sharing – looked at before listing). Plain text, ≤ 300 characters, no links (name the source). **With this line the maker confirms they may share all of it and that they, not the hub, answer for it**; on a rights holder's complaint the card comes off until it is solved. Ask the maker – never guess this line for them. Sounds from commercial instruments, sample CDs, games or records ("the Amen break") are not "own". | | `color` | The card's colour line (under the picture): `#RRGGBB`, e.g. `#FF7A00`. Bright enough for the dark page – a very dark colour is refused. | Valid JSON matters: double quotes, commas between fields, no comma after the last one, no comments. ### The SMK-37 card (https://thefirmwarehub.com/smk37/) A firmware with builds for the M-VAVE SMK-37 has a card there too, from the same file: - **A repository only for the SMK-37:** `what` and `image` above are the SMK-37 card's – nothing else to do. - **A repository shared with the FM-1 build** (one `fmhub.json` for both): the fields above stay the FM-1 card's; add an optional `smk37` block for what differs on the SMK-37. It wins over the fields above on the SMK-37 card either way. ```json "smk37": { "what": "An electric piano for the SMK-37's 37 keys, with vibraphone and marimba engines and an arpeggiator.", "image": "docs/smk37-card.png", "install": "https://you.github.io/yourfirmware/smk37/", "guide": "https://github.com/you/yourfirmware/blob/main/docs/SMK37.md" } ``` `what` and `image` follow the same rules as above; `install` (the SMK-37 installer) and `guide` are `https://` addresses. No other fields inside `smk37`. ## 3. The picture (`image`) - **Square**, between **240 × 240 and 1024 × 1024 pixels**. - **PNG, WebP or JPEG** (checked by the file's bytes, not its name). No SVG, no GIF. - **300 KB at most.** - Best: a capture of the FM-1's screen at exactly **240 × 240 as PNG** – a few KB, pixel-sharp (the hub scales it up without blurring). A photo of the device: square, 480–1024 px, as WebP or JPEG, well under 300 KB. - Many firmwares have a browser emulator or a host build that can save its 240 × 240 screen – use that, don't take a phone photo of the screen. - To change it later: replace the file, keep the path, push. The hub copies the picture and serves it itself. ## 4. Check before pushing 1. Validate the JSON (e.g. `python3 -m json.tool fmhub.json`). 2. Count the `what` text: ≤ 300 characters, English, no links, no `<` `>` `{` `}` or backticks. 3. Check the image: square, 240–1024 px, ≤ 300 KB, PNG/WebP/JPEG. 3a. Check `sounds` against the repository: a `"none"` with `.wav`/`.syx`/`.sf2` files (or sample arrays in the source) is refused. 4. After pushing, the maker enters the repository at **https://thefirmwarehub.com/kb/#fmhub** ("Check your file"): it shows exactly what the card will show, or what is wrong. 5. On the hub, every card says under its text whether it comes from the maker's `fmhub.json`, and if the file or the picture is not used, why. ## 5. Submitting a new firmware When all of section 1 is done, the maker sends one short mail to **zven@thefirmwarehub.com** (https://thefirmwarehub.com/submit/): - the firmware's name and the maker's name as it should appear, - the repository link, - its `FM-1_` identity and its licence, - that it was tested on a real FM-1 and leaving it again works. Text, picture, cheat sheet and links do **not** go in the mail – they come from `fmhub.json`. ## 6. Afterwards - New versions: just publish a GitHub release with the `.fwsc` attached. Same asset name and same identity is fine. - Card text, picture, cheat sheet, browser version, editor: edit `fmhub.json` (and the image file), push, wait up to three hours. Never mail text changes. - The maker's face on the Wall of Creators (https://thefirmwarehub.com/creators/) is their GitHub profile picture; a YouTube channel added to their GitHub profile's social accounts shows up there too.