Comprehensive RAUC Documentation Update

Enrico Jörns | | RAUC, Documentation

As in many projects, also in RAUC phases of extensive development did often not leave sufficient time to explain the latest changes, new features or at least some basic concepts in an appropriate manner.

  before after
lines 2135 3522
words 9275 16805
characters 66991 119992

As a result, not only useful and helpful features simply go by the board. Also the amount of questions and misunderstanding that might have been prevented by a good documentation increases over the time.

Therefore, Pengutronix decided to take the virtual pen and paper in the hand and extend and improve the RAUC Documentation in many places.

The result of that work is quite impressive if you look at the quantitative impact, for example. Taking the number of characters, the volume of the documentation has increased by almost 80%.

The structure and content of the introductory chapter, that presents an overview of fundamental concepts and ideas behind RAUC to the user has been completely redesigned and complemented by many aspects. In addition, some complex topics were accompanied with vivid graphics.

With the newly created chapter Scenarios some of the most common redundancy setups are discussed while configuration examples point out how to implement them with RAUC.

The important chapters on integration of Barebox and U-Boot were extended by technically more detailed instructions.

Also, a whole series of additional topics have been added, such as dealing with security, generation and handling of certificates, application data handling and migration, bootloader updates, or software deployment.

But, even if there are robust updating frameworks like RAUC, building an individually fitting and robust update concept requires much know-how and accuracy in assembling and configuring the different system components. From the selection of the boot loader over the watchdog set up and handling to the detection of a successfully booted user space various components must closely engage with each other.

With the newly introduced Design Checklist we have therefore developed a basic pamphlet, which (without claim on completeness) covers many general cases and possible pitfalls in the design and the implementation of update concepts.