Skip to content

Partition Layout

The BrioSens uses a NAND flash memory for storage. The NAND memory has a capacity of 4 Gbits (512MB) and has been partitioned in the following manner:

Partition UBI Volume Label Mount Point Mount Options Size
mtd0 N/A Secondary Bootloader N/A N/A 32MB
mtd1 ubi0_0 Storage /mnt/storage R/W 200MB
ubi0_1 Logs /mnt/logs R/W 30MB
mtd2 ubi1_0 Filesystem + Application Kernel / RO + OverlayFS 220MB

UBI stands for "Unsorted Block Images". It is a volume management system for raw flash devices.

The UBI volume layout of the mtd1 partition can be edited by modifying the /etc/ubi_volumes.conf file however the ubi0_0 (Storage) and ubi0_1 (Logs) volumes are mandatory.

Secondary bootloader (Boot Kernel)

When powered up, the i.MX28 processor runs the code from its internal boot ROM. The first stage bootloader loads the secondary bootloader located at the base address of the NAND memory.

The secondary bootloader partition is a read-only partition and is loaded during the boot process. This partition cannot be modified without burning a new kernel to the NAND memory.

The secondary bootloader is comprised of the following:

  • a boot kernel

  • a boot kernel device tree (dtb)

  • an initramfs (embedded in the kernel)

  • imx bootlet

The secondary bootloader is responsible for updating the filesystem and launching the application kernel.

A persistent and always read-only bootloader is installed on the system during production on mtd0.  It cannot be reprogrammed in the field. The bootloader uses a kernel+initramfs called the boot kernel.

The application kernel (loaded by the boot kernel) resides in rootfs located in /boot/zImage (mtd2). The boot kernel will fetch the application in the location mentioned above and boot this kernel at boot up.

To update the rootfs, the rootfs.tar.gz (with its associated rootfs.tar.gz.md5) file must be copied to the /mnt/storage folder (the storage partition). In the same manner, the application kernel can be updated by copying the zImage (with its associated zImage.md5) file to the same folder. Both rootfs and kernel application kernel can be updated at the same time. Upon reboot, the boot kernel will search for these files and perform the upgrade.

Storage

Located in /mnt/storage the Storage partition is a non-volatile partition used to store user files. The contents of this partition are maintained after reboot.

This partition also contains user configuration files (ex: Wi-Fi configuration) which can be modified and saved.

Warning

Since the BrioSens is not a battery operated device, corruption of the volume may occur if a write operation is interrupted by a power failure. To prevent this, we recommend taking advantage of the OverlayFS to write in volatile memory. When the volumes are corrupted, recovery mechanisms are in place to restore theses volumes to a known state. During the recovery process, the contents of /etc/default_storage are copied to the storage volume.

Logs should be saved in the logs volume while configurations can be stored under the storage volume. The user's application, however, should be installed in the filesystem since the volume is read-only. Regular updates of the /etc/default_storage folder will ensure that minimal data is lost in the event that the storage volume becomes corrupted.

Filesystem

The Filesystem partition is a read-only volume and comprised of the following:

  • an application kernel

  • an application kernel device tree (dtb)

  • an initramfs (embedded in the kernel)

The file system partition also contains the root filesystem (rootfs). Once mounted, files in the Filesystem can be created, modified or deleted. However, all files will be restored to their original state after a reboot.

Configurations required by rootfs use symbolic links to the Storage partition. This allows configurations to persist even after a reboot.

If the user needs to customize the filesystem, refer to the filesystem edit mode section for instructions.

OverlayFS

The BrioSens uses a read-only filesystem to prevent corruption caused by changes to the root filesystem. A reboot will restore the system to a known state.

BrioSens also uses an OverlayFS to allow temporary modifications, in volatile memory, of read-only files and folders.

OverlayFS allows you to overlay the contents (both files and directories) of one directory onto another. The simplest case (image below) involves two directories, each containing files and folders. We can think of them as “upper” and “lower,” with the rest of Linux and applications positioned above that. The “lower” directory is read-only. File access through the OverlayFS retrieves data from the “upper” directory first, and then defaults to the “lower” directory if a file doesn’t exist.

Customizing the filesystem

Warning

Modifying the file system may corrupt the system. If the BrioSens Gateway stops working after customizing the file system, use the file system provided by Briowireless to revert the changes.

There are two methods of customizing the filesystem:

  1. Using the filesystem
  2. Editing the rootfs.tar.gz tarball

Once customized and updated, the file system will become read-only and any changes to that file system will be restored after a reboot.

Using the filesystem edit mode

To modify the filesystem, enter the filesystem-edit mode:

systemctl start filesystem-edit

Warning

  1. Care must be taken when the device is in the filesystem-edit mode; a power failure may corrupt the filesystem
  2. When the device enters the filesystem-edit mode, the filesystem is re-mounted under /mnt/filesystem with read and write permissions. The filesystem can then be modified (adding, editing or removing files).
  3. Changes done under /mnt/filesystem will then be reflected under root / and will be persistent.

After completing the required modifications, exit the filesystem-edit mode:

systemctl stop filesystem-edit

To update other devices with the same changes, the modified filesystem can be compressed into a tarball:

updatePackager <output_path>

Editing the rootfs.tar.gz tarball

To edit the rootgs.tar.gz tarball:

  1. Obtain a copy of the original rootfs.tar.gz

  2. Decompress the rootfs.tar.gz

  3. Apply the necessary modifications

  4. Re-create the compressed archive. Make sure it is called rootfs.tar.gz

  5. Generate a checksum from the compressed archive and name it rootfs.tar.gz.md5 using the following shell command:
    md5sum rootfs.tar.gz \> rootfs.tar.gz.md5

Once both files (compressed archive and md5 file) have been created, follow the instructions in section Update Mechanisms to update the filesystem.