UBootEnv

CircleCI Hex version

This library lets you read and write U-Boot environment blocks from Elixir. U-Boot environment blocks are simple key-value stores used by the U-Boot bootloader and applications that need to communicate with it. Nerves uses U-Boot environment blocks to store settings related to the device and running firmware. Nerves uses the format even for boards (like the Raspberry Pis) that don't use the U-Boot bootloader.

This library has the following features:

  • Create, read, and write to U-Boot environment blocks in pure Elixir with OTP 21 and later
  • Fallback to uboot-tools for prior OTP versions (this has a known bug for multi-line values)
  • Support for /etc/fw_env.config for environment block parameters
  • mix utilities to manipulate the block offline

Not all U-Boot environment features are supported. The primary omissions are around support for raw NAND features like redundant environment blocks and awareness of erase block sizes. If you don't know what this means, it doesn't affect you.

Installation

Install by adding uboot_env to your list of dependencies in mix.exs:

def deps do
  [
    {:uboot_env, "~> 0.1.0"}
  ]
end

Mix tooling

The mix tooling is useful for inspecting and updating provisioning-related parameters on MicroSD cards and on raw images. For example, to inspect the environment block on a Raspberry Pi's MicroSD card, insert that MicroSD card in your computer. In the following example, the MicroSD card showed up at /dev/sdc. The U-Boot environment offset and size were found in the Nerves system's fwup.conf file.

$ mix uboot_env.read /dev/sdc 0x2000 0x2000
  a.nerves_fw_application_part0_devpath = "/dev/mmcblk0p3"
  a.nerves_fw_application_part0_fstype = "ext4"
  a.nerves_fw_application_part0_target = "/root"
  a.nerves_fw_architecture = "arm"
  a.nerves_fw_author = "The Farmbot Team"
  a.nerves_fw_description = "The Brains of the Farmbot Project"
  a.nerves_fw_misc = "beta"
  a.nerves_fw_platform = "rpi3"
  a.nerves_fw_product = "farmbot"
  a.nerves_fw_uuid = "7fd0682a-3294-521c-bfdc-9dafd2cfa558"
  a.nerves_fw_vcs_identifier = "f540f8d319ec10c20cf7870d3ad2bf907f67389d"
  a.nerves_fw_version = "6.4.12"
  b.nerves_fw_application_part0_devpath = "/dev/mmcblk0p3"
  b.nerves_fw_application_part0_fstype = "ext4"
  b.nerves_fw_application_part0_target = "/root"
  b.nerves_fw_architecture = "arm"
  b.nerves_fw_author = "The Farmbot Team"
  b.nerves_fw_description = "The Brains of the Farmbot Project"
  b.nerves_fw_misc = "beta"
  b.nerves_fw_platform = "rpi3"
  b.nerves_fw_product = "farmbot"
  b.nerves_fw_uuid = "005fdb61-d0ca-5c4d-051f-0ce127be7e7c"
  b.nerves_fw_vcs_identifier = "f2fe6481783740470d6a22fb1b7e7993e475239f"
  b.nerves_fw_version = "6.4.12"
  nerves_fw_active = "a"
  nerves_fw_devpath = "/dev/mmcblk0"
  nerves_fw_serial_number = "000000008d60fd86"
  nerves_hub_cert = ""
  nerves_hub_key = ""
  nerves_serial_number = "000000008d60fd86"

Information about most of these variables is in the nerves_runtime README.md. Of course, projects can add their own custom keys to this section too.

To write a new key-value pair, run the following:

$ mix uboot_env.write /dev/sdc 0x2000 0x2000 test "abc"
  ...
  test = "abc"

To delete that key-value pair, run:

mix uboot_env.delete /dev/sdc 0x2000 0x2000 test

License

This code is Apache 2 licensed.