Skip to content

Commit b95878f

Browse files
theacodestheacodes
committed
Add user guide
1 parent e3b67fe commit b95878f

File tree

5 files changed

+169
-0
lines changed

5 files changed

+169
-0
lines changed

‎user_guide/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
site/

‎user_guide/docs/css/overrides.css‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
h1 a, h2 a {
2+
color: #b8c6ca;
3+
font-size: 50%;
4+
margin-left: 0.4em;
5+
}
6+
7+
ul.nav li.first-level {
8+
display: none;
9+
}
10+
11+
footer small:last-child {
12+
display: none;
13+
}

‎user_guide/docs/images/honk-program-labels.png‎

915 KB
Loading

‎user_guide/docs/index.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Winterbloom Big Honking Button User Guide
2+
3+
Big Honking Button is, well, a big button that honks. Okay, that's not all- it’s actually a simple sampler in a very silly package. It has pitch CV, gate in, gate out, and you can store up to 4mb of samples on it.
4+
5+
## Getting support and help
6+
7+
We want you to have a wonderful experience with your module. If you need help or run into problems, please reach out to us. Email is the best way for product issues, whereas Discord and GitHub are great for getting advice and help on how to customize your module.
8+
9+
* Send us [an email](mailto:support@winterbloom.com).
10+
* File a bug [on GitHub](https://github.com/theacodes/Winterbloom-Big-Honking-Button)
11+
* Reach out on the [Discord][discord]
12+
13+
14+
## Installing the module
15+
16+
To install this into your Eurorack setup:
17+
18+
1. Connect a Eurorack power cable to your power supply and the back of the module. **Note that even though the power connector on the module is keyed, double check that the red stripe is on the side labeled `red stripe`!**
19+
1. Screw the module to your rack's rails.
20+
21+
22+
## Inputs and outputs
23+
24+
![images/honk-program-labels.png](images/honk-program-labels.png)
25+
26+
Big Honking Button has two inputs:
27+
28+
- A gate / trigger in
29+
- A pitch CV in that is 1v/Oct with a -2v to +2v range
30+
31+
And two outputs:
32+
33+
- A gate / trigger out (0v or 5v)
34+
- An audio out
35+
36+
37+
With the default code, it will trigger the sample and play it through the audio out whenever the button is pressed or whenever the gate input is triggered. It will also set the gate out to high whenever the button is pressed or whenever the gate in is high. You can customize some of this behavior by [modifying the code](#modifying-the-code).
38+
39+
40+
## Changing the sample
41+
42+
You can change the sample on Big Honking Button by connecting it to your computer via a micro USB cable. The USB port is located on the module's main circuit board, located under the panel. Please note that you do have to power the module in order for the USB connection to work (the module itself can **not** be powered over USB alone).
43+
44+
Samples must be in mono, 16-bit, 22kHz, signed `wav` files. Adafruit has an [excellent guide on how to convert sound files](https://learn.adafruit.com/adafruit-wave-shield-audio-shield-for-arduino/convert-files).
45+
46+
To modify the sample that plays:
47+
48+
1. Connect the Big Honking Button to your computer using a micro USB cable. It should show up as a small external drive named `CIRCUITPY`
49+
1. Navigate to the `samples` folder in the drive
50+
1. Rename or delete the existing `sample.wav` file
51+
1. Copy your sample over and rename it to `sample.wav`
52+
53+
Your Big Honking Button will reboot and then it should play the new sample! If you run into trouble, please [reach out](#getting-support-and-help).
54+
55+
You can store and play multiple samples on the Big Honking Button, but to do that, you'll need to learn how to modify some of the code - don't worry! It's not too hard.
56+
57+
58+
## Modifying the code
59+
60+
When connected to your computer, Big Honking Button shows up as a small drive named `CIRCUITPY`. In that drive, you should find a file named `code.py`. Big Honking Button runs [CircuitPython](https://circuitpython.org) which means that its firmware is written in the approachable [Python](https://python.org) programming language and you don't need any special knowledge or compilers to make changes to it. So, open up that file in your favorite text editor, we're going to make some changes!
61+
62+
If you don't have a text editor - that's okay! While you could use Notepad (Windows) or TextEdit (Mac), these can sometimes have issues with CircuitPython devices like Big Honking Button. I'd recommend [installing Mu](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor) if you're new to this whole world. You can read more about editing code for CircuitPython in [Adafruit's guide](https://learn.adafruit.com/welcome-to-circuitpython/creating-and-editing-code).
63+
64+
As a way to get your feet let's change how the Big Honking Button behaves. By default, when you press the button it plays the *entire* sample, even if you release the button while the sample is still playing (this is **trigger mode**). This will make it where the sample will stop as soon as you let go of the button (or **gate** mode).
65+
66+
In the `code.py` you should see some code that looks like this (it's at the bottom):
67+
68+
```python
69+
if bhb.released:
70+
bhb.gate_out = False
71+
# Uncomment the call to stop to make the sample
72+
# stop playing as soon as you release the button.
73+
# bhb.stop()
74+
```
75+
76+
Modify this code so that it looks like this:
77+
78+
```python
79+
if bhb.released:
80+
bhb.gate_out = False
81+
# Uncomment the call to stop to make the sample
82+
# stop playing as soon as you release the button.
83+
bhb.stop()
84+
```
85+
86+
!!! warning "Be careful"
87+
Python is *whitespace-sensitive*. That means tabs and spaces are important! Make sure that you don't accidentally change the indentation level of this line.
88+
89+
Okay, save the file! Your Big Honking Button should restart and now it should stop the sample as soon as you let go of the button, try pressing it rapidly to see the effect.
90+
91+
!!! note "Tip"
92+
If things aren't working, see the section below on finding problems or [reach out](#getting-support-and-help)!
93+
94+
**Congrats**, you've made your first change to how the module works! 🎉
95+
96+
Big Honking Button can store multiple samples and you can use various means to change how they're triggered. We'll be adding a sample showing just that soon, but don't be afraid to experiment and reach out if you need any help!
97+
98+
If you want to you can learn more about [CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/overview) to the most of your module. Also, please come chat on the [Discord][discord] where you can ask questions and see what others are doing with their Big Honking Button!
99+
100+
101+
## Help! I change some code and this thing isn't working!
102+
103+
There's probably some sort of error in the program. Don't worry, you can get it figured out.
104+
105+
If you connect using the [serial console](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console) you should be able to see the error. If you don't see it right away, you might need to reset the board (either by pressing the little button on the bottom of the module or power cycling your synth). Sometimes you can press `Ctrl+C` followed by `Ctrl+D` in the serial console to get the board to reset and tell you the error.
106+
107+
In any case, reach out on [Discord][discord] and we can walk you through figuring out what went wrong.
108+
109+
## Updating the firmware
110+
111+
Updating the firmware requires two steps: Updating CircuitPython and updating Big Honking Button's libraries.
112+
113+
### Updating CircuitPython
114+
115+
1. [Download the latest version of CircuitPython for Winterbloom Big Honking Button](https://circuitpython.org/board/winterbloom_big_honking_button/).
116+
1. Connect Big Honking Button to your computer via USB. The USB port is located underneath the panel. Note that you still have to power the module from a Eurorack power supply.
117+
1. Place Big Honking Button in bootloader mode by pressing the reset button twice quickly. The reset button is located on the bottom of the module just below the power connector. Once in bootloader mode, you should see a drive on your computer named `HONKBOOT`.
118+
1. Copy the `uf2` file from step 1 to the `HONKBOOT` drive. The module should restart by itself.
119+
120+
### Updating Big Honking Button's libraries
121+
122+
1. [Download the latest release bundle for Big Honking Button](https://github.com/theacodes/Winterbloom-Big-Honking-Button/releases).
123+
2. Unzip the release bundle, and then copy the contents to Big Honking Button's `CIRCUITPY` drive, replacing any existing files.
124+
3. Reboot Big Honking Button by power cycling your synthesizer or pressing the reset button again.
125+
126+
127+
<!-- ## Frequently asked questions
128+
129+
Got a question not answered here? [Reach out](#getting-support-and-help), we'll be happy to help! -->
130+
131+
132+
## Acknowledgments and thanks
133+
134+
Big Honking Button would not be possible without the help of the CircuitPython community and Adafruit Industries.
135+
136+
137+
[discord]: https://discord.gg/UpfqghQ

‎user_guide/mkdocs.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
site_name: Winterbloom Big Honking Button User Guide
2+
copyright: "© 2020 Winterbloom, licensed under Creative Commons CC BY-SA 4.0"
3+
repo_url: "https://github.com/theacodes/Winterbloom-Big-Honking-Button"
4+
edit_uri: edit/master/user_guide/docs
5+
theme:
6+
name: cinder
7+
hljs_languages:
8+
- python
9+
extra_css:
10+
- "css/overrides.css"
11+
markdown_extensions:
12+
- admonition
13+
- def_list
14+
- toc:
15+
permalink: "#"
16+
toc_depth: 2
17+
nav:
18+
- "User Guide": index.md

0 commit comments

Comments
 (0)