Can documentation be fun?

A project log for Long Range Machine Control System

LoRa + ROS Full Duplex Peer to Peer Data Transceiver Array with Onboard High Precision Satellite Positioning

Capt. Flatus O'FlahertyCapt. Flatus O'Flaherty 05/29/2022 at 10:130 Comments

Normally, in the recent past, I'd create a device or machine with all manner of fancy Ai equipped all seeing, all thinking, super fantastic sensation that even worked really well. But, and this is the big one, by the time I'd finished, I had pretty much no idea what all the components were, especially when it came to interactive files in the software stack. In one project, I ended up with a pretty crazy diagram showing how all the files interacted, but it just was not properly accurate for my liking.

One of the problems is that I like to work really fast and focus entirely on getting the project working. This time I am taking a more leisurely approach and am trying to create enough documentation to enable myself, never mind anyone else, to see how it was all pieced together. To do this, the documentation stages need to be enjoyable.

Due to previous experience in this particular field, I pretty much know 95% that this project is going to work really nicely as it is built on top of other previous successful projects. I believe that by doing the project a bit more slowly and methodically could be MORE enjoyable and taking a bit of time out to do some documentation could actually make it MORE fun and rewarding.

The first step in this new adventure is to keep track of the software stack as more files are added and not to lose track of how files interact with each other. Currently, as of May 2022, the stack is quite simple but, as the project evolves, this is likely to change quite radically. If I start iteratively updating the stack diagram after each major change, can I accurately keep track of it all? I am going to try, at least!

The diagram below is the second iteration - it's the second diagram I have produce so fat detailing the components of the stack. It's going to get much bigger as time goes on.

The eager eyed amongst us will notice that the stack is split into 2 halves and the right hand side is currently empty. So far, I've been working exclusively on the 'Nest' which is my own term for the control centre, or 'Mission Control' in NASA lingo. The choice of words for parts of the stack and the system in general is absolutely crucial as in previous projects I saw terminology, especially with regards to satellite positioning, deteriorate into a travesty of inappropriate descriptions. Other projects ended up with multiple use of the word 'base' which resulted in truly incomprehensible instructions. 'Base' is a banned word in this project and all parts of the system are to be described by objects in the animal kingdom including 'Nest', 'Dog' and 'Snout'. Nest is used to indicate that the device or part of the stack is physically located in the mission control room. We could then have Nest_Master to indicate that the device is the master in the ROS operating system in the Nest. Dog is a roving machine and dog_snout is the front of the machine. Trust me, this form of nomenclature is infinitely better than what seems to be the industry standard.

In the diagram above, the most crucial details of the stack in the nestmaster and nestslave are shown. Both these devices are Raspberry Pi V4's. There's also currently just one Arduino Mega 2560 called arduino_master_tx. I should probably re-name this to arduino_nest_tx in the next iteration of the documentation for extra clarity. There's also going to be an arduino_nest_rx to handle incoming radio waves from the dogs and any other machines out in the wilderness.

Another thing that might be slightly interesting, is that I will be backing up the SD cards or SSD's or whatever, regularly throughout the development so that there will always be at least 2 copies of each Raspberry Pi system. Also, the plan is to have fully duplicated SD cards (or whatever) for the main Raspberry Pis so that, for example, the Master SD card will contain all the files for all the Masters that exist in the entire ecosystem. Logically, I should probably change the word nestmaster to masternest, this being the case. This may sound trivial, but having properly logic defined names massively helps understand the system. The nomenclature of the system is constantly evolving at the moment!