DO-178C In Plain Text – Part 2
“Beauty of style and harmony and grace and good rhythm depend on simplicity.”
Greetings fellow humans 🌎 👫 (+ 🛸 👽 💻 🤖), and a very warm welcome to my second video. Thanks for clicking. 🙏
My name is Ed Liversidge, and I would like to present to you the second part of the radical game-changing process for safety-critical certification, involving nothing but plain text and free software.
Ed Liversidge, MD & CTO, Harmonic Software Systems https://harmonicss.co.uk
30th November 2023
In Part 1, I introduced the use of Spacemacs and the use of plain text to store all the artefacts that are used when certifying safety-critical software to the DO-178C standard.
I will demonstrate how I can apply Org Roam to the DO-178C software development process, to implement a powerful, trackable, traceable and just downright fantastic way of working within the otherwise painful DO-178C process.
A bit of background…
The Zettelkasten (German word for “slip box”) method of note taking has a long history with academics and scholars, and it’s use is often referred to as building a “second brain” 🧠.
It is often accredited to the German sociologist Niklas Luhmann, who indexed over 90000 cards and credited it for enabling his prolific writing of 70 books and 400 articles.
It consists of small items of information stored on paper cards, linked to each other through metadata or tags, and filed away for easy retrieval.
Figure 1: Zettelkasten Notes
Zettelkasten + DO-178C
Now, when I came across this method (only a matter of weeks ago, in fact), the one thing that stood out was the bi-directional linking between information.
I saw a connection here with the DO-178C standard for certifying aerospace systems, as this emphasises bi-directional traceability throughout the software development process, effectively following the V-model.
In addition, I had just finished up a DO-178C project, in which I was able to use Org Mode to document and manage the testing of an avionic mission computer and could see how I could extend this, not only to the entire software lifecycle but also to all the documentation that that is created for a certified system.
Org Roam is a Zettelkasten system implemented in Emacs, so for me, this presents an extremely powerful system to manage a DO-178C project. In fact, we can apply this to any software development process that demands the rigor of a safety-critical approach, such as automotive, defence, nuclear, medical or space.
One important point of the Zettelkasten system is that it is not a top-down hierarchy of information, it is more chaotic and disorganised, allowing links and connections to be discovered and creativity to flourish. So it remains to be seen if organising all the data in a DO-178C project is really going to follow the Zettelkasten approach, or if I am just taking advantage of the deep linking to better organise the data and prove traceability and coverage.
Demo 1 – Org Roam
Org Roam is the tool that integrates with Org Mode in Emacs / Spacemacs that allows for deep linking between text within Emacs Org files.
To start off, I am going to open a top level file
SETUP.org, which contains some setup code that will initialise the project. I wont go into the technical details here, but once this code is executed (by pressing
Ctrl-c Ctrl-c), then everything will be setup for this particular project.
These links can be searched very easily from within Spacemacs, using the following key command:
SPC a o r f : org-roam-node-find
This give me a searchable list of every node in the project. A node is every DO-178C artefact, whether that is a single document such as the SDP, a Low Level Requirement or Verification Procedure. I expect that there will be tens of thousands of nodes in a running project.
These nodes are managed via a sqlite3 database, which is included with recent
versions of Emacs, and provides a fast, efficient and highly customisable
back-end. I love their tagline : “Small. Fast. Reliable. Choose any three.” The
database is automatically regenerated after each save, and can be updated
manually with the Emacs command
Note The M key is the meta key, which is usually the ALT key on PC keyboards, or the Option key on the Mac.
In this case lets select the FILE-LLR001 that we looked at in the last project.
As I have said before, it is the traceability which is important for DO-178C, and Org Roam has a killer feature to visualise this.
Demo 2 – The UI
I can open the UI from any Org Roam buffer using
SPC a o r u
This opens the UI from your browser, showing a live graphical representation of all the links in the project. Note that we are at the beginning of the project, and there aren’t that many links yet.
Figure 2: Org Mode UI Node Display
The brilliant thing here is that as I move through each node in Spacemacs, then the UI follows along, enabling me to see the traceability.
I can move up to see the link to the HLR:
Figure 3: Org Mode UI HLR Node Display
Or down to the FUNC LLR, and then to each IMPLementation LLR:
Figure 4: Org Mode UI LLR Node Display
I can click a node to get info on the side window. Mouse over the linked references to see the connections. The visual traceability is fantastic.
Note : The FILE LLR links to the IMPL LLR which links to the Verification Case, except for LLLR001.01.11. which has no VC!
Demo 3 – Creating New Links
So, let’s create a new Verification Case to link to LLR001.01.11
So, I select the drawer and execute
org-id-store-link. Notice the
:PROPERTIES: drawer has appeared, with a unique ID assigned. Now I am able to link to this drawer, as a node in Org Roam.
Next I will create the new node for the VCs that will test this LLR.
a o r c : org-roam-capture name it HSS-IMX8-BL-VC-LLR001.11.org
This brings up a capture menu. Select ‘v’ to create the VC, and this opens a new capture buffer.
Now, that has created a new node for the VC, given it a unique id, styled it according to a capture template and placed it in the correct directory for the VCs.
I can link to this from the FUNC, by selecting:
SPC a o r i : org-roam-node-insert
The newly created node is at the top of the list, select it and voila! We have our link!!
Now I like to create the backlink, which in Org Mode can be found automatically with
SPC a o r l : org-roam-buffer-toggle
I like to put them in explicitly as I create them, so the traceability back up is easy to follow.
Insert another link from VC-LLR001.01.11 to IMPL-LLR001.01.11 using
org-roam-node-insert, using the ‘verifies :’ label.
I like to keep some clue reinforcing the traceability in the name, in case something goes wrong and gets confusing.
Demo 4 – The Agenda View
I have one more killer feature to show you today – The Agenda View.
To open the agenda, simply type
, a n. This gives me a list of all the OPEN or TODO items throughout the entire project (they were recursively added when I executed the setup code).
I can select
F (follow mode), and then this opens each item as I cycle through the agenda. Fantastic!
Ok, I can already read your mind. So I have a bunch of tasks, but this is no good if I can’t assign the work to someone. Well this is easy, I can assign tags with
,i t and add the name of the person I have assigned the work to. If I assign to a top level drawer, then all the lower drawers inherit the tag. So for instance if I want ‘bob’ to work on the FILE-LLR and implement all the LLRs into code then I can just assign the FILE-LLR to ‘bob’, like so.
Now I can filter on the tag with
, a m and search for all bob’s assignments. Once Bob has finished on a task, he can mark it for review (which a
shift right-cursor) and check it into git.
Or I can filter on the drawer states with
, a t. In this case
5 r shows up all the TODO-AI keywords that the AI has permission to work on. It is so powerful and flexible.
Figure 5: Org Agenda for DO-178C Task Assignment
This is a software engineering tool that I have adapted for software engineers to use to gain mastery of a DO-178C project.
Yes there is a steep learning curve with Emacs (Spacemacs), Org Mode, Org Roam, but as a software engineer this is what we do, this is what we are good at. Throw away the mouse, learn the keybindings (which are easy to change), master the tool and replace the mind-numbing trawl through endless excel and word docs with fast and efficient plain text.
We are treating all the meta-data in our DO-178C project (all the documents, the design, the requirements, the test code and even the test evidence) we are treating all this as code. Searchable, traceable, trackable, linkable plain text as code using open source tools that empower the users, saving time and money.
At my company, all my engineers strive to master this tool. I hope the same can happen in your company. If not, then I hope you have a great system that allows for instant searching, deep linking and powerful traceability throughout the entire project. Having a free tool is a bonus as well.
You will notice aswell that there is very little use of the mouse. Speed and efficiency are key here.
I still have alot to do with this – it is work in progress. I need to look at a PR system – I can integrate Jira, or I could easily have my own PR system that links directly to the item to be fixed. I need to have a review checklist – again easy to do. I would like to have an RSS feed for project updates, of course Emacs has many readers for this.
So thanks for making it to the end of the video.
I hope that you have started to get a taste for just how powerful this approach is. Certainly I can’t wait to get my teeth into the next DO-178C project using plain text because it is just so dammed powerful and we have not even scratched the surface on what we can achieve with the levels of customisation that are available with this editor.
In addition, now that the entire project is in plain text, my AI LLMs can read and write every bit of data on the project. I have AIs that I have trained up on the DO-178C standard. They can write and review documents, review requirements, perform checklist reviews, produce design documents etc. Really we are in a new age here.
If you would like a quick demo, please go to the contact page on my website https://harmonicss.co.uk/contact and get in touch.
We have also created a new Linked In group to discuss AI within the DO-178C framework, you can join here: https://www.linkedin.com/groups/12921667/
That’s it for now. In the next video I will showcase some of the AI working.
Don’t just take my word for it, let me show a few quick examples of other people using Org Roam
Mathematics with Org Roam
Org Roam to study the bible