Consider adding visual cheatsheet (RFC)

[philipbelesky]

Hey, thanks for this firmware! As part of learning the different modes it offers, I've been trying to make a cheatsheet pdf that is relatively comprehensive and draws from the docs here as well as for the original firmware.

This is my current draft of the document: Stages Cheatsheet 2021-11-20.pdf

Would this be something you would like hosted as part of this repo? Or that you would like to link to from the docs? If so, I'd be happy to make a PR.

Separate to that, I would love any feedback or comments on the design and information included. I've tried to dig out precise values for things like envelope/LFO times, etc ... although in some cases I've had to eyeball things on a not particularly accurate scope. I'm also not totally sure if some of the iconography or layout coding I've used makes sense. As mentioned, I'm a relatively novice user so I may also have misunderstand some of the modes or parameters!

[qiemem]

Wow, this is amazing! Thank you so much! Yes, I would love to host this in the repository. I think a link in the manual plus images in respective sections (which I can do) would be great, if you're okay with that.

Feedback: First impression is that it looks awesome and extremely comprehensive. A couple quick things that might help with quickly finding info (if there's reasons not to do these things, totally understand; just first impressions):

• I think a title on each page saying what that page is would help with finding what you want at a glance. e.g. it me a sec to realize that the first page was segment behavior in a group, and then to realize that subsequent pages were single segments behaviors.
• Similarly, I think some iconography next to the four different subtypes for single segment labels might help. e.g. segment type led with looping or not and then something to represent gatedness. Right now, you have to look at the top of the page at the led type light to get looping type, then bottom middle to get gatedness, and then bottom to get what it is. I think just having that information also next to the label might help with quick scanning.
• I absolutely love the patch ideas at the end. What a great quick reference!
• Iconography and layout looks fantastic in general. It's a lot of info and can be slightly overwhelming, but I think that's the fault of the firmware not the doc. It does a great job presenting it all.
• You might consider flipping pages 2 and 3 to match segment order.

A few more specific things (is there a way that you would like inline feedback? I could markup the pdf or just write it here; or if you have a preferred way to receive feedback, let me know). This is all pretty small stuff. Overall, I'm blown away by the depth of knowledge this took:

Page 1:

• The presence of sustain on the first page seems slightly odd to me as that's just what looping does in groups (makes segments repeat with gates). But maybe it's just a commonly enough needed info that it should be there? Also I would've expected the random segments to be there (though tbh I'm not very happy with their behavior in groups). You might consider adding "loop for sustain" to the other red segment and then replacing the sustain segment with a random segment.
• In each shape circle on the ramp segment, one the curves needs to be flipped around the vertical axis since (I assume) one curve should be rising and one falling.
• The voltage range for quantized segments is 0v to 2v for unipolar, -2v to 2v bipolar

Page 2:

• Slew curves should be flipped around vertical axis. In general, slew results in decelerating curves, while that shows accelerating.
• Same note about quantized ranges
• Why the difference in iconography between S&H's slew and slew's slew?
• "CLOCKED ATTENUV" should be "S&H w/ ATTENUV" or something. It doesn't care if the trigger is rhythmically clocked or not. Clocked LFOs, for instance, actually predict clock cycles. CV input should also probably be "Sampled CV" to match S&H.

Page 3:

• For rise in R/F slew, all curve should be decelerating up. The only difference is in time, not shape. Also, you might consider dropping the drop at the end of the curve. That threw my at first.
• You might consider using symmetric iconography on the slider. Pot and slider behave exactly the same. Just one is fall time one is rise time.
• I'm not sure this is worth presenting, but the mul/div values in upper and lower range of LFOs skip values at the extremes. But not sure how you'd fit that info in there.

Page 4:

• Quantized ranges

Page 5:

• Just a heads up that random segments are about to change a lot:
  • Nonlooping, nongated will be the smoothly chaotic source
  • Nonlooping, gated will still be Turing Machine
  • Looping, nongated will random LFO with, frequency ranges and all. The top frequency range will be 32khz to 8khz, and then lock at pure noise (32khz) at the top. See this post for descriptions of the new smoothing behavior at each pot position: https://forum.mutable-instruments.net/t/stages-qiemems-alternative-firmware/17506/130?u=qiemem. Still tweaking a bit, but that should be close to final.
  • Looping, gated will be clocked random LFO with identical muls/divs/ranges as other LFOs.
• I love the representations of the different chaotic behaviors. How did you come up with those?
• Segment type icon is currently marked looping for all subtypes.

Page 6:

• I think DAHDSR is all right, though TBH, I never use it.
• I've added mul/div ranges to the harmonic sliders in harmonic oscillator mode. Divs are 1/16 to 1. Muls are 1 to 16. I can't remember if range is still controlled by slider in mode 5... I'll get back to you.

Page 7:

• I don't totally understand the blue labels on the slider
• Slew is decelerating in general.
• Again, love the patch ideas. I definitely will have some I'd love to see there, but we can discuss later :)

Again, just amazing job here. I'm completely blown away. Thank you so much for all the work you put into this! I think people will find this incredibly useful.

If you'd like specific values, or would like to see the actually generated curves for anything, just let me know. Happy to provide whatever information would be helpful. Also, I'll try to give you a heads up with other changes coming, though I think I listed them all here (besides bug fixes).

[philipbelesky]

Hey, thanks for getting back to me with such comprehensive feedback!

With regards to the changes, a marked-up document makes sense. I'll work through the bullet points here over the next week or so and post up a revision for further feedback.

Just a heads up that random segments are about to change a lot:

Roughly how far away do you think these changes are (on the scale of weeks vs months)? I'm just asking as it may make sense to 'launch' the cheatsheet alongside the new version so there's no need to worry about maintaining an older version.

I love the representations of the different chaotic behaviors. How did you come up with those?

I've worked with chaotic attractors in a visual domain, so I was just drawing very rough sketches of typical shapes from memory. I'm assuming it's not possible to have meaningful shapes here and so the set is just meant to indicate 'the shape control makes different types of random path'. I'd totally be game to try and draw meaningful shapes if possible.

I don't totally understand the blue labels on the slider

These are the PLAY / HOLD labels? IIRC, with the extender sequencer mode, that first slider segment controls playback state - at 0V it will advance and at 8V it pauses. The blue sub-labels intend to show that if you do the HOLD+WIGGLE mode, the inverted polarity means that 0V pauses and 8V advances. I think I checked this behaviour in-rack, but I only learned about this part of the original firmware a few days ago so I might be missing something.

[qiemem]

Hey, thanks for getting back to me with such comprehensive feedback!

Everything was so clearly laid, it was very easy to go through quickly!

Roughly how far away do you think these changes are (on the scale of weeks vs months)?

Hopefully weeks, not months, but hard to say. I think releasing the next version and the cheatsheet together makes sense.

I'm assuming it's not possible to have meaningful shapes here and so the set is just meant to indicate 'the shape control makes different types of random path'. I'd totally be game to try and draw meaningful shapes if possible.

As I mentioned, I really like the shapes you've drawn. If you are interested in drawing more directly representational shapes, one thing I'd note is that unlike many chaotic modules, we're only getting one dimensional output (though the underlying system is three dimensional). So a value over time line would also make sense. If you're interested, you can play around with the chaotic system here:

https://netlogoweb.org/launch#https://gist.githubusercontent.com/qiemem/e36e443c8808a5a1d4e3bb33ed6900d3/raw/bc53e3c9a3193145a1923f69027f706730d03cd3/chaos.nlogo

That model should match module behavior almost exactly as I used it to tune everything. The plot marked "Output" is what the module outputs. The slider marked "pot" corresponds to the actual module pot.

But, again, current representation is great too, so no need to change it unless you want to.

The blue sub-labels intend to show that if you do the HOLD+WIGGLE mode, the inverted polarity means that 0V pauses and 8V advances. I think I checked this behaviour in-rack, but I only learned about this part of the original firmware a few days ago so I might be missing something.

Wow, really? That was definitely not intentional :stuck_out_tongue_closed_eyes: Um, if that is the case, I'll probably toss it. I don't think I meant for hold+slider to do anything on extended sequencer. That said, maybe it should control voltage range or quantization scale or something...

[philipbelesky]

Ok, updated file here: Stages Cheatsheet 2021-12-01.pdf

Happy to work with an annotated PDF for future changes (either here or over email; whatever is going to be most convenient). Anything not explicitly noted below should be done (but let me know if I missed anything).

General Notes

Similarly, I think some iconography next to the four different subtypes for single segment labels might help. e.g. segment type led with looping or not and then something to represent gatedness. Right now, you have to look at the top of the page at the led type light to get looping type, then bottom middle to get gatedness, and then bottom to get what it is. I think just having that information also next to the label might help with quick scanning.

I was originally using borders and underlines to show these stages, but that definitely seems to have been too cryptic. I've moved the icons used inline down to be adjacent to the titles - hopefully these are relatively clear.

Segments page

In each shape circle on the ramp segment, one the curves needs to be flipped around the vertical axis since (I assume) one curve should be rising and one falling.

Ah, of course. I think for simplicity's sake I'll just show the rise state

Also I would've expected the random segments to be there (though tbh I'm not very happy with their behavior in groups). You might consider adding "loop for sustain" to the other red segment and then replacing the sustain segment with a random segment.

I've added these in, although this means the page dimensions are no longer printable. That said, I don't think the cheatsheet works well at less than A3 size anyway, so I think it's probably fine to design it for screens foremost?

Yellow Page

Slew curves should be flipped around vertical axis. In general, slew results in decelerating curves, while that shows accelerating.

How do the updates look?

Why the difference in iconography between S&H's slew and slew's slew?

In the context of a slewed S+H, my thought was to depict a stepped signal becoming increasingly smoothed as that seemed like a more typical use of slew in S+H. But it's probably not worth making that distinction. Or, at least, I can't be bothered during a proper slewed stepped curve just yet.

Red Page

I'm not sure this is worth presenting, but the mul/div values in upper and lower range of LFOs skip values at the extremes. But not sure how you'd fit that info in there.

What does skip values here mean? Like they skip the period resets? So at fast rates they would retrigger before cycling, and at slow rates they would fail to retrigger immediately after a cycle?

Red-Green Page

Looping, nongated will random LFO with, frequency ranges and all. The top frequency range will be 32khz to 8khz, and then lock at pure noise (32khz) at the top. See this post for descriptions of the new smoothing behavior at each pot position: https://forum.mutable-instruments.net/t/stages-qiemems-alternative-firmware/17506/130?u=qiemem

These look great! Should I just take the scope images (sliced to a small time subset) as the icons for the knob?

Remaining TODOs

• [ ] Mul/Div ranges for harmonic mode
• [ ] Drawing chaos shapes per the netlogo output

Waiting on

• If slider controls range in mode 5
• New red-green random behaviours/params
• More patch ideas?

[qiemem]

Great stuff! Will get back to you with feedback when I've had a chance to go through it all.

[qiemem]

This is such great work! Thank you again! Almost all the feedback is small corrections: [Stages.Cheatsheet.2021-12-01.Feedback.pdf](https://github.com/qiemem/eurorack/files/7736647

I was originally using borders and underlines to show these stages, but that definitely seems to have been too cryptic. I've moved the icons used inline down to be adjacent to the titles - hopefully these are relatively clear.

Very much so! Super clear now.

I've added these in, although this means the page dimensions are no longer printable. That said, I don't think the cheatsheet works well at less than A3 size anyway, so I think it's probably fine to design it for screens foremost?

I suggest a way to get back to printable size in the doc (don't think you need separate segments for the looping variants of red and random). I actually would expect people to print it out FWIW. I know I have a bunch of printed cheat sheets for various modules...

How do the updates look?

Perfect!

What does skip values here mean? Like they skip the period resets? So at fast rates they would retrigger before cycling, and at slow rates they would fail to retrigger immediately after a cycle?

No, sorry, I mean that it doesn't cover all the mul/divs between highest and lowest. So, for instance, muls are x1, x2, x3, x4, x5, x6, x7, x8, x12, x16.

These look great! Should I just take the scope images (sliced to a small time subset) as the icons for the knob?

Totally up to you! In general, CCW is more periodicity, less crazy, and CW is less periodicy, more, spiky, more crazy, but there's lot of phase transitions in there so... Like I said, I like your depictions, but if you wanted real examples of curves, you can get them from there :). Oh, I realized that the frequency calculation differs between model and module; the model uses default LFO range, and the module runs slower.

Mul/Div ranges for harmonic mode

Oh woops. I added them in the doc. Forgot I already gave them to you.

If slider controls range in mode 5

Confirmed that it does.

New red-green random behaviours/params

• I haven't changed from the MI forum post much I think. That should be a fine reference. From CCW to CW, it's approximately:
  • Uniformly random, stepped
  • Uniformly random, with sine like transition curves, plateaus at values (so the curve is flat at each random value, but S-shaped between values)
  • Uniformly random, with sine like transition curves, slight plateaus at values
  • Uniformly random, fully splined transitions. The slope of the curve at each point will be pointing to the next point.
  • Random walk, large step-size, splined transitions
  • Random walk, medium step-size, splined transitions
  • Random walk, tiny step-size, splined transitions.
• Frequency ranges in document

More patch ideas?

Added to doc! Take or leave as you see fit.

Sorry it took me so long to get back to you! I really appreciate all the work you're putting into this. It's really fantastic stuff and will be such a usability improvement!

[philipbelesky]

Hey, no problem, thanks for the feedback. A revised copy is here: Stages Cheatsheet 2021-12-18.pdf

I think I have done all of the comments posted to the PDF. Let me know if I missed anything.

Printing

I suggest a way to get back to printable size in the doc (don't think you need separate segments for the looping variants of red and random). I actually would expect people to print it out FWIW. I know I have a bunch of printed cheat sheets for various modules...

I have shrunk down the segments in groups items to fit one page so this should be all good. Currently my document is A3-formatted but it scales down to A4 reasonably well when I last tested. I probably won't have access to a printer for a few weeks but i'll aim to refine some of the type and element sizes at a later stage.

Green-Red

Uniformly random, fully splined transitions. The slope of the curve at each point will be pointing to the next point.

Do you mean that the tangent approaches the horizontal at the midway point before flipping? This is roughly what I drew for the 12:00 position.

For the other CCW shapes, I just used an approximation using corner rounding. Let me know if these need tweaks. I kind of drew the description rather than the scope signal thinking that this makes the parameterisation (e.g. smoothing, step size) more apparent.

Also, to confirm for the clocked random LFO:

• What would be the best option for the shapes here be? Just the same as the normal random LFO?
• When you say the frequency/divisions are the same as the other LFOs, is that the same as the green-red random LFO or the green LFO? (I used the latter)

Common Configs

I've added the suggested configs. Let me know if any of the other items need the clarifying (gray) text.

A visual patchbook, as suggeseted in the doc, would be great although I'm probably not up for spending the time to do it. If you (or anyone else) is handy with Illustrator though, I can provide my source .ai. Everything is setup as symbols, so it might be pretty easy to put together different configurations on a full mockup.

Misc

I've added a brief credit line and version string to the last page. Let me know if I'm missing any credits or if you'd prefer just 'qiemem' for the byline.

[qiemem]

Looks great! Had just one comment on pages 1, 2, and 7: Stages.Cheatsheet.2021-12-18.Feedback.pdf

I have shrunk down the segments in groups items to fit one page so this should be all good. Currently my document is A3-formatted but it scales down to A4 reasonably well when I last tested. I probably won't have access to a printer for a few weeks but i'll aim to refine some of the type and element sizes at a later stage.

Looks great printed at US Letter! Oh, as an aside, my printer is b&w which got me thinking about color blindness in the doc. But it looks like you already handled that. I mean, doesn't work in monochrome, but fairly legible for both red-green and blue-yellow color blind. Not sure if that was intentional, but it's a nice touch!

Do you mean that the tangent approaches the horizontal at the midway point before flipping? This is roughly what I drew for the 12:00 position.

Your drawings do a perfect job of portraying it! FWIW, it doesn't have to flip to go horizontal; it will go horizontal at each "tick". So at 9:00, even if it goes from 2v to 5v to 7v, it will plateau at each value. But at 12:00, it won't. The drawings are spot on.

What would be the best option for the shapes here be? Just the same as the normal random LFO?

Same as normal random LFO is great!

When you say the frequency/divisions are the same as the other LFOs, is that the same as the green-red random LFO or the green LFO? (I used the latter)

Same as green LFO. It's correct as is.

If you (or anyone else) is handy with Illustrator though, I can provide my source .ai.

I am not, but including the .ai files (depending on size) in the PR would be great!

I've added a brief credit line and version string to the last page. Let me know if I'm missing any credits or if you'd prefer just 'qiemem' for the byline.

@joeSeggiola made the original multi-mode firmware and is entirely responsible for the mode switching, the DAHDSR mode, the alternate harmonic oscillator mode, etc. Not sure if @-ing notifies the person if they're not in the thread, but in case it does, Joe, would you mind being included in the credits in the illustrated manual of this firmware?

[philipbelesky]

Regarding the "Step ASR", thanks for providing the link — that post was super useful when I was implementing a Turing-Machine style register (e.g. binary sequence) as part of a Teletype project a few weeks back.

In terms of the terminology, I remember reading somewhere the Tom Whitwell preferred projects avoid using "Turing Machine" as its more of a brand name for that particular module rather than a particular implementation. It's probably a moot point given the constrained space available for the text anyway. Would just "Shift Reg" work? The labelling of the "Bit Flip Chance" might be enough to give a hint of the particular implementation — and there's always the full manual.

[qiemem]

Regarding the "Step ASR", thanks for providing the link — that post was super useful when I was implementing a Turing-Machine style register (e.g. binary sequence) as part of a Teletype project a few weeks back.

Oh nice! Glad it was useful.

In terms of the terminology, I remember reading somewhere the Tom Whitwell preferred projects avoid using "Turing Machine" as its more of a brand name for that particular module rather than a particular implementation.

Ah good call. I kind of had that sense anyway (and thus say "emulation of Tom Whitwell's Turing Machine" or something to that effect in the manual). If you happen to remember where you read that, I'd be curious to hear more of what he says on the topic.

Would just "Shift Reg" work? The labelling of the "Bit Flip Chance" might be enough to give a hint of the particular implementation — and there's always the full manual.

"Shift Reg" would probably be fine. That is what Hemisphere for O_C uses. Any chance there's room for "Shift Reg.", to make it clearly an acronym for the circuit rather than reference to the applet? "DSR" (for "digital shift register") is another possibility, though a quick search pretty much only bring up https://www.modulargrid.net/e/omiindustriies-dual-digital-shift-register rather than the use of "digital shift register" as a name for the circuit.

[philipbelesky]

That all sounds good, and "Shift Reg." fits. That, and other updates below:

Stages Cheatsheet 2021-12-26.pdf

Not sure if the firmware update is still likely to change before release, but let me know when you'd like a PR with the pdf and source file.

[qiemem]

Great! This looks awesome. Go ahead and open a PR.

Couple minor corrections on page 5:

• Middle period for the default range of the chaotic type is 8s... if I'm doing my math right (v/oct, 0v to 8v, so 7 is 1s, 6 is 2s, 5 is 4s, 4 is 8s...)
• Top period of the default range of random LFO should be 0.03s. It's correct on the hold & slide thing, just not on the main slider.

[joeSeggiola]

@joeSeggiola made the original multi-mode firmware and is entirely responsible for the mode switching, the DAHDSR mode, the alternate harmonic oscillator mode, etc. Not sure if @-ing notifies the person if they're not in the thread, but in case it does, Joe, would you mind being included in the credits in the illustrated manual of this firmware?

Sorry, I have just seen this discussion now. I'm perfectly fine with how you @philipbelesky included me in the credits. And btw, awesome work.