How to go about documenting your setup?

Possibly the single most important thing that separates science from "fiddling around" is documentation. Figuring out how to document things is often non-trivial and me telling you that "unless you wrote it down, it didn't happen" only goes so far.

If documentation isn't your thing, what about "I broke something and I don't know how it was before I fiddled" as an incentive instead?

Recently I had cause to explore how to document how my station is configured. To give you a sense, the microphone is connected to a remote-rig, which is connected to a Wi-Fi base station, over Wi-Fi to a Wi-Fi slave, to another remote-rig, to the radio body, to the VHF port, through two coax switches, a run of RG213, to an antenna.

When receiving, it goes from the antenna, to a run of RG213, through two coax switches, to the VHF port, to the radio body, to a remote-rig, to a Wi-Fi slave, to a Wi-Fi base station to a remote-rig, to the remote head, to a set of headphones.

Of course, at this point I've written it down, so, job done .. right?

Well, what about the data connection, the external speaker, the remote head display and other goodies, say nothing of the duplicate devices with similar names. All in all, the FT-857d has something like eleven ports, each remote-rig has ten, so just wording it is a start, but hardly qualifies as documented.

What if we drew a picture instead? At this point you could pull out your crayons and start scribbling on a sheet of butcher's paper and that would be a fine start, but it would be difficult to share with me or anyone else and updating it would be a challenge, let alone versioning it.

As it happens, we're not the first people to have this issue. In the 1980's and 1990's researchers at Bell Labs were trying to figure out how to draw graphs and from that work a language, 'DOT', since everyone is a fan of the "DAG Of Tomorrow", and a series of tools, which today are known as 'Graphviz', made the visualisation of relationships possible without the application of coloured wax on dried cellulose fibre.

In my other, computing job, I had cause to visualise the relationship between a million or so nodes, allowing me to discover a specific node that was directing all traffic, where I could insert my debugging code, but it was only possible thanks to these free and open source tools.

While the DOT language isn't particularly complex, it occurred to me that for someone not conversant with the syntax, we can start even simpler with a CSV text file that shows the relationships between each device and convert the CSV to DOT and in turn to a picture.

For example, I documented the relationship between the radio and the antenna by adding five lines to a CSV file, essentially, FT857d to VHF port to VHF coax switch to VHF grounding switch to RG213 to antenna.

In all, to document everything except power, since I haven't decided how I want to describe it, I used a CSV with 47 lines. On the face of it, that might sound ridiculous, but I can tell you, it shows all the sockets on the FT857d, all the sockets on both remote-rig devices and the relationships between them. With it anyone can duplicate my set-up.

Having previously spent some quality time learning various aspects of the DOT language, I figured I could write a little script to convert CSV files to DOT, but being of the generation of software developers with the attitude, "Why write something if someone else already did?", I discovered that Reinier Post at the Eindhoven University of Technology has a delightful collection of scripts, including one appropriately named 'csv2dot'.

Written in Perl, the only language that according to some looks just as impenetrable before and after encryption, the tool works as advertised and makes a DOT file that you can then visualise using Graphviz.

Of course there's Python scripts lying around that claim to do the same, but I wasn't keen to install the kitchen sink just to try them. Instead I made a quick little Docker file that you can find on my vk6flab GitHub repository that will walk you through this, complete with my example, so you have a starting point.

Now, I used this here to describe my station, well, one part of it, but it can easily extend to document your entire station, and because we're talking about text files that contain the information, anyone with a copy of a text editor can update the file when things change, since that's where the real magic happens.

So, what are you waiting for, documentation?

I'm Onno VK6FLAB

Building a shack makes a number of assumptions about your situation and to make it abundantly clear, it's not the only way to enjoy the hobby of amateur radio. Visiting clubs locally and remotely, being a member of a club, visiting other amateurs, setting up your station in a suitcase or a backpack, on a bicycle, in a car, on a bus, or in a boat are some of the many other avenues open to you.

That said, there is something magical about building your own shack. It has the ability to transform your hobby and if you have the opportunity, I can highly recommend it and I'd like to encourage you to consider the notion.

As I've said previously, there is plenty of exploration and learning associated with putting one together. After you've spent some time reflecting, planning, designing, sourcing, building and testing the environment where you do amateur radio, you're likely to reach a point where you'll refer to that space as "your shack". You might even come to think of it as your shack, rather than a collection of trade offs that you've constructed in the best way you know how.

Inevitably, you'll wonder what to do next.

Several things come to mind. Creature comforts is probably the most obvious, a push to talk foot pedal, or a desk microphone, either on a stand or hanging from a boom, an audio mixer, a couch, a soldering station, a microwave oven, a fan, or air conditioning, in other words, plenty of opportunities for improvement and enhancement.

Then there's computing, something that might interest you, or not. It offers the ability to explore a whole different side of amateur radio, from logging through to digital modes, from weak signal propagation to tracking satellites, the possibilities are endless.

Your shack is also potentially a communal place where you can meet with your friends to share the experience.

It's a place for contemplation, for relaxation, for "being" an amateur. All of it is open to you as possibility, an excuse to improve and enhance.

The thing is, that too will come to a point of, let's call it "completion", and you're left with more questions.

Amateur radio is inherently experimental in nature, that's the whole point of the pursuit. Your licence gave you access to the playground, your shack is that playground. Now it's up to you to play.

Of course what playing looks like is unique to you. Over the past 15 years I've been describing what playing looks like to me, and from the over 3 million downloads last year from my website alone, not to mention the newsletters, rebroadcasts, podcast inclusions, other streaming services, news reports, social media and messages I've received, they've encouraged you to explore and investigate this wondrous activity.

The point is, the shack you just completed isn't finished and hopefully it never will be. Whichever one it is, the first one, the one after that or the next one, your shack is a place where you can experiment, learn, discover, test, fail, succeed, challenge and enjoy the hobby of amateur radio. It's not the only place where you'll find this hobby, but it's your place.

So, have at it.

I'm Onno VK6FLAB