Skip to content

Commit

Permalink
Tweak formatting in DEVELOPING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Dewb committed Oct 17, 2024
1 parent 5ac5eb3 commit 0448b5c
Showing 1 changed file with 24 additions and 24 deletions.
48 changes: 24 additions & 24 deletions DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,38 +75,38 @@ Start a hot-reload server with `mkdocs serve`, and run `mkdocs build` to produce
1. First, make sure you can build the plugin using the instructions in either [Building the plugin using the Rack SDK](#building-the-plugin-using-the-rack-sdk) or [Building the plugin using the complete VCV Rack source](#building-the-plugin-using-the-complete-vcv-rack-source) above.
2. Optional: Sign up for a [GitHub] account and create a new fork in your own account for the firmware repo for the module you want to to modify.
3. Create a new firmware submodule inside the `firmware` folder. Let's say we want to create a new development version of the teletype firmware and call it `teletype-dev` within the Rack environment.
```bash
$ cd monome-rack
$ cd firmware
$ git submodule add https://github.com/<your user name>/teletype teletype-dev
```
```bash
$ cd monome-rack
$ cd firmware
$ git submodule add https://github.com/<your user name>/teletype teletype-dev
```
4. Run `git submodule update` again to make sure we have the submodules of the new submodule.
```bash
$ git submodule update --init --recursive
```
```bash
$ git submodule update --init --recursive
```
5. Add `teletype-dev` to our list of firmware binaries to build and add to the plugin. Edit `Makefile` in the monome-rack root folder and under the `firmware-build:` section, add the line:
```
cd firmware && $(MAKE) -f teletype.mk TARGET_NAME=teletype-dev
```
Make sure is indented with a single tab character, like the other lines in the section.
```
cd firmware && $(MAKE) -f teletype.mk TARGET_NAME=teletype-dev
```
Make sure this line is indented with a single tab character, like the other lines in the section.
6. Rebuild the plugin using `make install` or the Visual Studio Code **Run Build Task...** command, as in step 1.
7. Run Rack and place a Teletype module. You should be able to see `teletype-dev` as one of the choices in the **Firmware Tools** > **Switch Firmware** right-click menu. Switch to it! You're now using the code from the new submodule folder you created in step 3.
8. Let's make some changes to the code. Open `firmware/teletype-dev/module/live_mode.c` and go to line 771. Change the string `"TELETYPE "` to something else, like `"HELLO "`. Leave the space at the end of the string.
9. Rebuild the plugin again as in step 6.
10. Run Rack again, and now any Teletype modules in your patch running the `teletype-dev` firmware should say **HELLO** on the startup screen instead of **TELETYPE**.
11. Now you can make some more substantial changes. Fix a bug, add a new feature, or erase everything and create a completely new module.
* Note: if your goal is to create new behavior for the module from scratch, you'll need to preserve the `initialize_module()` and `check_events()` functions, but most everything else is fair game. You'll need to use the `DECLARE_VRAM` and `DECLARE_NVRAM` macros on your key data structures to have them preserved in the Rack patch. Compare the `whitewhale` and `whitewhale-kria` submodules to see and example of two different firmware for the same module.
* Modifying the firmware can't change anything about the Rack "virtual hardware"; it will have the same panel, with the same inputs, outputs, and controls. If you're making something new, pick the module that best aligns with the I/O needs of your new idea. (The name of the firmware determines which module the firmware will be available for, and therefore which panel and I/O will be used, so when you create the new submodule, make sure your submodule folder name starts with the name of the base module.)
* Note: if your goal is to create new behavior for the module from scratch, you'll need to preserve the `initialize_module()` and `check_events()` functions, but most everything else is fair game. You'll need to use the `DECLARE_VRAM` and `DECLARE_NVRAM` macros on your key data structures to have them preserved in the Rack patch. Compare the `whitewhale` and `whitewhale-kria` submodules to see and example of two different firmware for the same module.
* Modifying the firmware can't change anything about the Rack "virtual hardware"; it will have the same panel, with the same inputs, outputs, and controls. If you're making something new, pick the module that best aligns with the I/O needs of your new idea. (The name of the firmware determines which module the firmware will be available for, and therefore which panel and I/O will be used, so when you create the new submodule, make sure your submodule folder name starts with the name of the base module.)
12. When you have made something interesting and want to share it, you'll need to commit back to your firmware fork. It's probably a good idea to first create a branch:
```bash
$ cd firmware/teletype-dev
$ git checkout -b my_new_feature
```
```bash
$ cd firmware/teletype-dev
$ git checkout -b my_new_feature
```
13. Now push that branch to your fork:
```bash
$ git push -u origin my_new_feature
```
```bash
$ git push -u origin my_new_feature
```
14. Note that this will *not* create any commits in your local copy of the monome-rack repo. This is okay, as you don't need to commit the changes to Rack to add your development firmware. You can share the firmware binaries from the `res` folder to other people and they won't have to build anything. Alternately, they can add your firmware to their build environment themselves by following steps 3-6, with one change to add the `-b` option to the `git submodule add` command:
```bash
$ git submodule add -b my_new_feature https://github.com/<your user name>/teletype teletype-dev
```
```bash
$ git submodule add -b my_new_feature https://github.com/<your user name>/teletype teletype-dev
```

0 comments on commit 0448b5c

Please sign in to comment.