Build your own commercial module part 3: firmware and documentation

2023-12-28 design digital byocm MSK 014

There's a lot more to a commercial module design than just the physical module that you can touch. If, as is the case with many new designs, the module includes any kind of computer, microcontroller, or other programmable device, then you need to have the program for that device. Usually, the program will be called firmware - software that becomes part of the hardware. Even a module without a conventionally programmable CPU in it may need something like an FPGA bit stream. Even a basically analog design may have some programmable aspect. For instance, my Leapfrog VCF design was originally intended to be programmable for different filter curves by substituting different resistor values on one of the three circuit boards. Creating this intangible programming information is part of creating the module, but also separable from the main task of circuit design.

Documentation is another necessary task in getting a module to market, and it's one that often requires special skills for which you may need to hire external help. Even if it's obvious to you how your module would fit into a patch, it may be less obvious to your customers. Before they even become your customers, you need to communicate what the module does and why it's valuable. After someone has one of your modules, you need to explain how to use it. You may also need other, more technical kinds of documentation, like a build guide for a DIY project, or a service guide for whoever will repair or maintain your product.

In this part of the "build your own commercial module" series, I'll look a little more deeply at some of the firmware and documentation issues. You may want to start with part 1 if you haven't already read it.

A platform for your firmware

Your design concept should ideally focus on what the module does, and not how it does it. That focus on externally-visible functionality leaves a lot of space for different choices in how the module works internally, and one of the choices you make later is exactly where to draw the line between hardware and firmware.

For instance, a simple modular-synth sequencer might have eight knobs, clock and reset inputs, an output that steps between the voltages set by the knobs, and maybe some blinking lights. The now-discontinued Pittsburgh Modular Sequencer is a good example. The Doepfer A-155 is a well-known modular step sequencer with a few more features but filling much the same role.

One way to implement a basic sequencer is using several single-function MSI CMOS logic chips, like the 4017 or 4022 counter/dividers, driving analog switches to connect one panel pot at a time to the output driver. You end up with maybe three or four chips in a straightforward circuit. There are many schematics for such sequencers on the Net, and people tend to call this an "analog" sequencer design even though it really is digital, just to distinguish it from a circuit based on a programmed microcontroller, which might somehow feel even more "digital."

Classic modular sequencer designs often date from an era when using discrete logic chips was the only practical way to get the job done. There's a lot of both nostalgia and inertia in the design community, especially the DIY design community, leading people to continue using old-fashioned discrete-logic techniques in new designs today. But today a 4017 costs just as much as a microcontroller with thousands of times its functionality, so the microcontroller becomes an attractive alternative.

Most commercial designers today would maybe keep the analog switches, but replace all the MSI CMOS logic with a single microcontroller chip and firmware telling it to close one switch at a time in response to the clock and reset inputs. Using a microcontroller replaces a few tens of transistors on the MSI chips, with perhaps a hundred thousand transistors in the microcontroller. But by reducing the number of chips, the microcontroller despite its internal complexity is in some sense actually a simpler circuit, and, importantly, it will cost less money to build. Using a microcontroller also means you can easily build in extra features, like maybe separate modes to go backwards through the steps or choose steps at random, which a 4017 could not practically support.

Which way is better? That's hard to say; but I can say that high-volume commercial projects today almost always end up going the microcontroller route just because it's cheaper. It's also more flexible, allowing the possibility of upgrades and development changes by reprogramming the firmware without needing to change the physical circuit. Then as soon as you decide to build something that will contain firmware, you have a requirement for someone to write the firmware.

Budgeting time for writing the firmware is important, as is having a realistic appraisal of your own - or your contractor's - firmware development skills. I've sometimes commented that Mutable Instruments is or was not really a hardware company at all, but a software company that just happened to sell its software products in elaborate packaging - because the interesting and innovative parts of the best-known Mutable modules were all features of the firmware, running on otherwise pretty ordinary and straightforward microcontroller boards. Without the firmware, on just the strength of the hardware designs, most of us would never have heard of Mutable. That's a great way to go if you can make it work, but it is a very different focus from the analog designs for which some other manufacturers are known. Nobody is able to be top of the heap in every dimension, and it's important to know your own strengths.

Depending on how much effort and skill you can bring to firmware development, you may make different choices about what kind of hardware platform will run your firmware, and those choices create feedback between firmware development and other stages of hardware development. For instance, many projects may start on a ready-made hardware platform like a Teensy, Arduino, or Raspberry Pi for initial development and prototyping. One might even eschew hardware entirely at the earliest stages, and try out ideas on a desktop computer in Csound, Pure Data, or VCV Rack. After doing development on a ready-made platform, once you're ready to build hardware you can just build a Eurorack front panel with maybe some op amp buffers and attach the Teensy or whatever to the back of it, running something very close to the code you wrote during earlier development stages. Or you can build a hardware design from scratch, with some appropriate microcontroller chip that might be quite different from the platform on which you did most of your development, and then you have to translate or "port" the firmware.

Using a ready-made board means less work in both hardware and software development, but probably also more expense, and quite likely compromises on issues like power consumption and HP width of the final product. Designing a completely new single-board microcomputer for your module project increases the development effort because it means someone must actually do that design work, and port the firmware to the new platform. But it brings down the cost per unit compared to a ready-made platform, and it may have other advantages. Which one is better, is an issue you'll have to sort out when planning your project.

In the MSK 014 Gracious Host I opted for a complete from-scratch microcontroller design. I don't know whether that was the right call. I was intrigued by finding a Microchip PIC24F microcontroller with USB support in a through-hole package. Almost any other computational platform with USB would have required going to surface-mount construction and a resulting compromise on DIY friendliness. But, especially given my displeasure at the dubious licensing of the Microchip C compiler, this microcontroller selection meant programming the Gracious Host firmware entirely in assembly language. That was extra work for me, and I have prior experience in assembly language. It created what might be a prohibitive learning curve for many others who do not have such experience. If I had chosen to make the module a little wider and a little more expensive, using a ready-made development board with surface mount components on it, then I might have been able to get the same USB support in a less austere development environment, which would make it more attractive to other programmers as well as saving development time.

Third-party firmware and upgrades

Mentioning "other programmers" raises an interesting question with respect to firmware: do you anticipate others besides you creating and distributing firmware for your module? Depending on how you imagine your module being used, and how you intend to market it, third-party firmware might be anywhere from the whole purpose of your module in the first place; to an unintended and unsupported but harmless thing some few users might attempt at their own risk; to a really detrimental thing you'd try to forbid them from doing. There is also the separate but related question of your own company distributing upgraded firmware versions in the future. If you want or expect new firmware to be loaded onto your module in the future, whether it's from you or third parties, you may need to design a mechanism for firmware-loading into the hardware and into the first firmware right from the start.

If your customers will be loading new firmware in the field, regardless of its origin, then that capability has implications for the hardware platform. Ready-made development boards, your Arduinos and similar, can usually plug into a personal computer over USB for reprogramming, or just contain something like a micro-SD card that can be swapped out. If you want it to be easy for your customers to load new firmware, these boards make it easy; if you want it to be hard, these boards may be less appealing.

If you're building a more customized hardware design with a microcontroller on a chip and less ready-made infrastructure for the firmware, then being able to load new firmware can present a challenge. Single-chip microcontrollers are often designed to be "programmed" with a special, separate hardware tool which your customers probably won't have. If you want customers to be able to load new firmware without sending the module back to you or something, then you face extra work to design in the firmware-upgrade feature. It won't come for free. Maybe your microcontroller can reprogram itself under software control without the separate programming device, making stuff possible like "play a special audio file into the CV input to load new firmware"; but really making such a feature work can be tricky and depends on low-level details of the microcontroller you are using.

In the Gracious Host, I considered it important for users to be able to load firmware from inserted USB sticks. Okay, that was part of the design concept and I treated it as a priority. But there's a lot of code needed to talk to the USB stick at all. It is difficult for that code to replace itself while maintaining communication with the USB stick to load the new code. The first version of the firmware-loading code turned out to only work well with one individual USB stick that I happened to have used for most of my testing, necessitating a small-scale recall to install a new firmware version on deployed modules that couldn't be upgraded in the originally-intended way. The "upgrade from USB stick" feature, which sounds simple enough in an initial design document, ended up meaning that I had to include a whole extra chip in the hardware just to buffer new firmware images - increasing the retail price of the module - as well as imposing a fair bit of extra work in software development. And all that work had to be done in assembly language.

Apart from the technical challenges of upgradable firmware, you have to think about the extent to which you want to invest in ongoing development work to create future versions of your firmware; and the extent to which you want to encourage or discourage third-party firmware.

It may be nice to imagine your module being the platform at the center of an "ecosystem" or programmers' community, where many users are creating and sharing their own firmware. It seems like if you could get people doing that, network effects would increase the value of your module and drive sales. Many modules are designed from the start with third-party firmware as a major design goal.

From my own experience and observation of others' experiences, I am pessimistic about the idea of creating an ecosystem around a programmable synth module. I've tried; I'm just not sure I should have. Far more companies have attempted to sell programmable modules to attract third-party firmware development than have succeeded. The central issue is perhaps appropriate for late December when I'm posting this:

You can't tell anybody what to do with a gift.

You don't get to choose the purposes for which third parties will write alternate firmware. Instead of implementing an innovative new synthesis algorithm, third-party firmware's functions may be like "increase the range of this knob half a point"; "make this buffer longer"; or even "disable what you considered to be the main purpose of your module because someone wants to use it as a generic reverb instead." Third-party firmware authors will discover exciting new ways to accidentally annoy you, like maybe naming one of the modes as a pun on your name, which is just fine and a respectful gesture, until you change your name and wish everybody would stop mentioning the old one. If you put a lot of effort into creating tools for firmware development for your platform, the tools may only be used for cloning your firmware into someone else's module that is 2HP narrower. And when the third-party firmware breaks, guess who the users will call for technical support, without mentioning that they loaded alternate firmware. Of course, this is all if you're lucky enough to have people write third-party firmware in the first place. Most "programmable platform" modules never actually get that.

I myself have a strong ideological commitment to technical openness. I'm not going to tell you that you necessarily should not encourage third parties to develop their own firmware for your module. It is difficult, likely impossible, to prevent third-party firmware from existing, especially when you use a ready-made hardware platform. So as a practical matter you may be better off encouraging it rather than fighting a losing battle trying to prevent it. But when you get your tenth or your hundredth tech support case from someone who thinks the only meaning of "free software" is that nobody ought to pay you, then you'll find out how committed you really are to your ideals - especially if, like me, you're playing on hard mode by hoping to make a living.

A different possibility might be to not have the firmware upgradable in the field at all - neither with upgrades from you, nor in a third-party ecosystem. Then you don't need to do the extra work to implement an upgrade feature. But then you had better get the firmware right the first time, because changing it means scrapping existing modules. If you are using a small microcontroller to replace a few MSI chips, just because the microcontroller is cheaper, then you may be able to specify from the start exactly what that microcontroller will do; make sure it does exactly that; and never need to change it until you redesign the module. In this kind of case, the firmware can be thought of as just another part of the hardware, like the traces on the PCB. The simpler the function the microcontroller is performing, the easier it is to make such a call. Firmware embedded in things other than microcontrollers, such as the programs for FPGAs and CPLDs, often can be treated this way.

Documentation

Every module needs text and graphics to explain how it is used. You might think the markings on your front panel are enough to guide users; but first of all, that is unlikely to be true, and second, even if true it would only mean that those markings are part of the documentation. Someone still needs to create them.

It is usually expected that a module will have some kind of user's guide explaining its functions. In some cases, for instance if you are selling a DIY kit, there will also be a need for instructions on how to build it. In some markets there can be regulatory requirements for documentation to include things like warranty statements (or even just the statement that there is no warranty), safety warnings, notices about waste disposal, and so on. You will also need ad copy - some description of the module that makes it sound appealing, for posting on online storefronts, inclusion in catalogs, and so on, to convince people they want to buy it.

How much documentation you provide, and its style, can become part of your branding. Some manufacturers present a product much like any other piece of audio equipment, with a manual that goes through the functions and specifications systematically. Others try for a "psychedelic" impression by writing a manual that talks vaguely about how cool the module it, with a lot of exclamation points and creative syntax, but never really saying quite what it does. The idea may be that discovering by experiment how the module works is supposed to be part of the fun the customer is buying. There may even be some idea of intellectual property involved: we don't want to disclose exactly what algorithm this module implements for fear someone else will "steal" the idea. But I fear that when manufacturers offer "psychedelic" user manuals, it's often just because they aren't capable of writing proper manuals, and it's not a seriously thought-out decision made for important reasons.

Written communication is a skill, as much as electronic design or any other creative skill; and there's no shame in the fact that as the party responsible for the design concept and running the business, you yourself may not be the one who can write the best possible manual for your product. Documentation is an especially good area for hiring a contractor to help you. At the very least, you might consider paying someone to read over the documentation after you've written a draft, to make editing suggestions. That usually costs less than getting professional writing done completely from scratch, and even a little bit of professional editing can significantly improve the value of your documentation. It's the sort of thing I sometimes do for my consulting clients.

For my own North Coast Synthesis modules, I've opted to make use of some of the skills and technology I used in my earlier life as an academic researcher, with highly verbose and formally-written user manuals that double as build guides for the DIY versions. I also include a detailed circuit explanation for each module, describing the underlying theory of how it works. For the Gracious Host I wrote a second manual just for programmers, going through how the firmware works. Part of the concept here is to set my products apart by doing something most of my competitors are unable to do. And this effort has been successful in that my North Coast Synthesis user manuals now have a reputation for educational value. I often see people on Web fora suggesting to electronics beginners that they should visit this Web site and read the manuals for my modules, as a way of learning synthesizer electronics in general.

But was that actually a good decision? What people are saying is read the North Coast manual - they aren't so much saying buy the North Coast module. I only get paid when people buy the module, and having my manuals be well-regarded only causes increased sales through a second-order effect by bringing people to the Web site. I can go broke while being highly respected, if respect does not mean buying products. This may be a structural problem in my business, and it may be a reason others perhaps shouldn't invest heavily in documentation. You have to decide for yourself what is the right level of documentation effort for your business.

Apart from the words themselves, graphic design of your documentation can be surprisingly important. Even a detail like the choice of font makes a difference in how people will feel about the manual and therefore the product. Take a look at these samples.

The top line is Charter. Words written in Charter feel like they are in a printed book. The second line is Latin Modern. That is the default typeface of LaTeX, and the one I use most often in North Coast Synthesis manuals. It is the voice of academic papers, especially in mathematics and computer science, and anything written in it ends up feeling like it might be an academic paper. The third sample is Comic Sans, and it feels much the opposite. Words written in Comic Sans feel like an inexperienced person dashed them off on a cheap word processor. That is the voice of garage sale posters. Depending on the impression you want to create, you might strongly prefer one of these over the others for your documentation.

The fourth line in the example is Souvenir - a typeface which was extremely popular in the 1970s in the USA. As someone who grew up reading American electronics magazines from that era, anything written in Souvenir puts me into a nostalgic space, because it feels like I'm reading one of the ads in those old magazines again. If you were advertising to an audience of people like me and wanted a 1970s flavour, this typeface would be valuable. On the other hand, if you wanted to present something as a brand new innovation of the 21st Century without ties to the past, then using Souvenir would be a bad idea because of its dated feel.

The last line of the example is Tsukurimashou Bokukko, a specialized display face which I use as part of the North Coast Synthesis branding both on this Web site and on module front panels. It is informal like Comic Sans, somewhat resembling felt-marker handwriting, but it also has a unique flavour readers are unlikely to see anywhere else.

Your documentation needs to be designed in much the same way that your circuits and physical module construction need to be designed. It's worth spending time on that, and possibly paying for professional assistence in getting it right. Documentation may be important to the overall success of your module project.

The idea is sometimes floated these days that language models like ChatGPT will soon make human writers obsolete. I'm not holding my breath for that, especially when it comes to module documentation, because it seems clear that such models have a lot of trouble with factual information, the most important part of the documentation. I've talked a lot about style above, style is important, and style is where these automated systems tend to do their best. With proper use a language model can do a good job of creating text that sounds like a well-written technical manual. For that reason, they can be valuable in the editing process, if you can make sure the facts are solid and only need help with the style. But the models require close supervision because left to their own devices, they tend to write text that is not actually true. A language model is not a database and it is not a search engine. It has very little connection to the meanings of the words it uses, nor to any source of factual knowledge. For that reason, language model output tends to be repetitive nonsense full of invented references and simply false statements. If you must use one, you'd better supervise it closely. Nonetheless, there may be contexts like Web log entries where you just need a few hundred words of filler without much emphasis on what it means, and in that case, a language model may be a cheap and effective way to fill in the blanks.

To conclude, building your own commercial module may involve a fair bit of writing - both writing software that becomes part of the hardware, that is, firmware, and writing documentation for human readers. One of your design decisions will be how much of the module's functionality to implement in hardware as opposed to firmware; and related to that are the questions of what roles firmware upgrades and third-party firmware will play. As for documentation, there are a number of kinds of documentation and different approaches you might choose to take. This is an area where professional assistence may be valuable. And style of the documentation is worth thinking about even beyond the content of the words, because it forms part of the image and experience of your module that you are creating for your customers.

◀ PREV Build your own commercial module part 2: design and development || Build your own commercial module part 4: manufacturing NEXT ▶

MSK 014 Gracious Host

US$246.27 including shipping

Comments