STICKY: HOWTO: Raspi HAT EEPROM and device-tree

[martinlbb]

Hi everybody,

As it is hard to find good quality information EEPROM for HATs, and after some struggling, I decided to write this post to clarify the process. I have made a tgz archive with all example files explained below, including ready to use EEPROM binary:

file.tgz

All file needed for this example, including eeprom ready file

(618 Bytes) Downloaded 1791 times

As a preliminary step, you need to activate videocore I2C. This is done by adding a line at the beginning of your /boot/config.txt file :
Add:

Code: Select all

dtparam=i2c_vc=on

Then reboot.

First of all, you need to get EEPROM utils (to make EEPROM content and flash it) and device-tree compiler (dtc).
For the device tree, I followed advice from Adafruit : https://learn.adafruit.com/introduction ... an-overlay

Code: Select all

git clone https://github.com/raspberrypi/hats.git
wget -c https://raw.githubusercontent.com/RobertCNelson/tools/master/pkgs/dtc.sh
chmod +x dtc.sh
./dtc.sh

You'll have now installed dtc compiler and have a hat directory. Go inside, and open eepromutils directory.

Code: Select all

cd hat/eepromutils

First of all, you need to modify eeprom_settings.txt to create your own version of HAT board. You don't have to modify UUID, as it will be auto-generated.

Code: Select all

########################################################################
# EEPROM settings text file
#
# Edit this file for your particular board and run through eepmake tool,
# then use eepflash tool to write to attached HAT ID EEPROM 
#
# Tools available:
#  eepmake   Parses EEPROM text file and creates binary .eep file
#  eepdump   Dumps a binary .eep file as human readable text (for debug)
#  eepflash  Write or read .eep binary image to/from HAT EEPROM
#
########################################################################

########################################################################
# Vendor info

# 128 bit UUID. If left at zero eepmake tool will auto-generate
# RFC 4122 compliant UUID
product_uuid 00000000-0000-0000-0000-000000000000

# 16 bit product id
product_id 0x0001

# 16 bit product version
product_ver 0x0002

# ASCII vendor string  (max 255 characters)
vendor "Martinlbb"

# ASCII product string (max 255 characters)
product "Brilliant board"


########################################################################
# GPIO bank settings, set to nonzero to change from the default.
# NOTE these setting can only be set per BANK, uncommenting any of
# these will force the bank to use the custom setting.

# drive strength, 0=default, 1-8=2,4,6,8,10,12,14,16mA, 9-15=reserved
gpio_drive 0

# 0=default, 1=slew rate limiting, 2=no slew limiting, 3=reserved
gpio_slew 0

# 0=default, 1=hysteresis disabled, 2=hysteresis enabled, 3=reserved
gpio_hysteresis 0

# If board back-powers Pi via 5V GPIO header pins:
# 0 = board does not back-power
# 1 = board back-powers and can supply the Pi with a minimum of 1.3A
# 2 = board back-powers and can supply the Pi with a minimum of 2A
# 3 = reserved
# If back_power=2 then USB high current mode will be automatically 
# enabled on the Pi
back_power 0

########################################################################
# GPIO pins, uncomment for GPIOs used on board
# Options for FUNCTION: INPUT, OUTPUT, ALT0-ALT5
# Options for PULL: DEFAULT, UP, DOWN, NONE
# NB GPIO0 and GPIO1 are reserved for ID EEPROM so cannot be set

#         GPIO  FUNCTION  PULL
#         ----  --------  ----
#setgpio  2     INPUT     DEFAULT
#setgpio  3     INPUT     DEFAULT
#setgpio  4     INPUT     DEFAULT
#setgpio  5     INPUT     DEFAULT
#setgpio  6     INPUT     DEFAULT
#setgpio  7     INPUT     DEFAULT
#setgpio  8     INPUT     DEFAULT
#setgpio  9     INPUT     DEFAULT
#setgpio  10    INPUT     DEFAULT
#setgpio  11    INPUT     DEFAULT
#setgpio  12    INPUT     DEFAULT
#setgpio  13    INPUT     DEFAULT
#setgpio  14    INPUT     DEFAULT
#setgpio  15    INPUT     DEFAULT
#setgpio  16    INPUT     DEFAULT
#setgpio  17    INTPUT     DEFAULT
setgpio  18    OUTPUT     DEFAULT
#setgpio  19    INPUT     DEFAULT
#setgpio  20    INPUT     DEFAULT
#setgpio  21    INPUT     DEFAULT
#setgpio  22    INPUT     DEFAULT
#setgpio  23    INPUT     DEFAULT
#setgpio  24    INPUT     DEFAULT
#setgpio  25    INPUT     DEFAULT
#setgpio  26    INPUT     DEFAULT
#setgpio  27    INPUT     DEFAULT

Then, you can create an eep file, based on you eeprom_settings.txt file. Basically, an eep file is a binary version of this file, which is ready to flash on EEPROM.

Code: Select all

./eepmake eeprom_settings.txt myhat.eep

You have now a working HAT file!

You can now write it on EEPROM. If you have followed the design guide, you have a 24c32 memory (4k). But your myhat.eep file is smaller. As you don't know the state of your EEPROM, you may have conflict, as your myhat.eep could be misread. To avoid that, we shall start by cleaning EEPROM.

Use this dd command to generate a 4k file, padded with zero (an excellent choice, zeros are my favorites!). If you have another EEPROM size, just change count value according to your real EEPROM size.

Code: Select all

dd if=/dev/zero ibs=1k count=4 of=blank.eep

To be sure, you can review this binary, using hexdump :

Code: Select all

hexdump blank.eep

Next, you can now upload it to your EEPROM :

Code: Select all

sudo ./eepflash -w -f=blank.eep -t=24c32

Answer yes, and before hitting enter, do a ground connection to test point (see design guide recommendation), who remove read-only flag. Then, press enter and wait without moving this ground connection!

To verify if everything went well, you can use this command to check EEPROM content. Caution: it will only work after you use the eepflash command, which does some modprobes.

Code: Select all

sudo hexdump /sys/class/i2c-adapter/i2c-0/0-0050/eeprom

If everything is okay, you'll only see zeros.

Then, you can upload your own myhat.eep.

Code: Select all

sudo ./eepflash -w -f=myhat.eep -t=24c32

And again, verify it after uploading :

Code: Select all

sudo hexdump /sys/class/i2c-adapter/i2c-0/0-0050/eeprom

If the contents match, you can reboot your Raspberry Pi.

To check if your HAT is recognized, just go to /proc/device-tree/. If you see a hat directory, you are a winner:)

Code: Select all

cd /proc/device-tree/hat/
more vendor
more product

The next step is to allow autoconfiguration of this HAT, following device-tree usage. In our example, we have a led connected to GPIO 18 (pin 12). I suggest you to test it before, using /sys/class/gpio :

Code: Select all

sudo sh -c 'echo "18" > /sys/class/gpio/export'
sudo sh -c 'echo "out" > /sys/class/gpio/gpio18/direction'
sudo sh -c 'echo "1" > /sys/class/gpio/gpio18/value'

Your led is powered on. And to power off :

Code: Select all

sudo sh -c 'echo "0" > /sys/class/gpio/gpio18/value'

Don't forget to get back to your hat/eepromutils directory after !

Now we can dive in the device-tree world. Open a file, called myled.dts, and paste this code (heavily copied from fividi post viewtopic.php?f=29&t=97875):

Code: Select all

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2708";

    fragment@0 {
        target = <&leds>;
        __overlay__ {
            my_led: myled {
                label = "MYLED";
                gpios = <&gpio 18 0>;
                linux,default-trigger = "heartbeat";
            };
        };
    };
};

Compile it with dtc compiler :

Code: Select all

sudo dtc -@ -I dts -O dtb -o myled.dtb myled.dts ; sudo chown pi:pi myled.dtb

For testing purposes, you can load this dtb as an overlay, using dtoverlay= in /boot/config.txt. This is not the purpose of this post, I let you search it on this forum.

Now, we can generate a eep file containing both board definition (eeprom_config.txt) and device-tree (for kernel auto configuration).

Code: Select all

./eepmake eeprom_settings.txt myhat-with-dt.eep myled.dtb

Then, blank the eeprom and upload it (don't forget to ground the test point to disabled read-only mode):

Code: Select all

sudo ./eepflash -w -f=blank.eep -t=24c32
sudo ./eepflash -w -f=myhat-with-dt.eep -t=24c32

And finally, consistency checking by viewing both original file and eeprom dump :

Code: Select all

hexdump myhat-with-dt.eep
sudo hexdump /sys/class/i2c-adapter/i2c-0/0-0050/eeprom

Finally, do a reboot, and enjoy your LED, blinking like a heartbeat!

Final reminder: When you start playing with adding long device tree, keep in mind you have a limited memory (4096 bytes for a 24c32 memory). When creating an eep file with eepmake, this tool will give you final size of your eep. Just verifiy if you have exceed your EEPROM size.

Note: With an incorrect DT, even your eeprom_settings are not recognized by kernel. And a bootable device-tree overlay is sometimes not sufficient for "eeprom boot"

To allow auto configuration after kernel boot (ie: modprobe some modules, TFT calibration, etc...), I use a custom parameter file, based on JSON, that could be parsed after. I choose JSON as it is small, human-readable, and easy to parse.
To add a custom file to your eep, just do this:

Code: Select all

./eepmake eeprom_settings.txt myhat-with-dt.eep myled.dtb -c myparams.json

[marcel_h]

Splendid!

[karrika]

Thank you for a very nice tutorial.

[PhilE]

That is a good tutorial. I just want to add two things:

1) There is an easier way to install dtc (at least for Raspbian users):

Code: Select all

sudo apt-get install device-tree-compiler

2) In most cases (i.e. provided your source is readable by user pi) it should not be necessary to run dtc as root. Running it as pi removes the need for the subsequent chown.

[6by9]

PhilE: Just a daft thought.
Pi3 is using i2c0 for other stuff off the GPU (GPIO expander mainly). Dom's comment to me was that there wasn't a safe way to access it from the ARM. Is there a need to revisit how to program HAT EEPROMs, or provide an option to disable all VPU access to i2c0 with the reduction in functionality that entails?
I suspect that at the moment trying to run this on a Pi3 is going to be intermittent or fail.

[PhilE]

It's not a daft thought - it's one that's been touched on here. Ideas (not all of which may be equally viable) include a mailbox command to lock out/disconnect VPU access, a dedicated VPU-based EEPROM writing service and a full remoted ARM->VPU I2C service.

[6by9]

It's not a daft thought - it's one that's been touched on here. Ideas (not all of which may be equally viable) include a mailbox command to lock out/disconnect VPU access, a dedicated VPU-based EEPROM writing service and a full remoted ARM->VPU I2C service.

OK, as long as it's on the radar. As with so many things I guess it's a matter of resource.

[musskopf]

Nice post!

I just have one question... about the JSON file, how do you actually access it later? Will the content be readable somewhere?

Once I get home I'll do some tests, but it seems to be exactly what I need to set some GPIOs states at the boot time. I've couple of GPIOs connected to "reset" pin of a few components and having them on the right state at boot is easier than use a script to re-configure and re-load the modules.

Also, is there a way I can have a similar config.txt inside the EEPROM? There are a few parameters my HAT requires so would be perfect if all work as plug-and-play, without any modification to the config.txt, for example, to enable SPI.

Cheers

[JamesPi123]

How do you connect the eeprom to the Pi for flashing?

[FeroxCannibal]

I have the exact same question how do I connect my eeprom with ground when I am at home? Is there no other way to get rid of the read-only mode??

And just a questions since it seems I didnt got it, I just have to have a working overlay for the flash? Since I am working now with a dynamic overlay which I get working with the dtoverlay commandline command. And it works, so I just have to flash it, no further edits in the file to make it hat compatible??

Edit: maybe with a jumper cable from a ground gpio of the pi? but how could I hit the ground leg of the eeprom if it is tiny?

[Dirk1980ac]

I have the exact same question how do I connect my eeprom with ground when I am at home? Is there no other way to get rid of the read-only mode??

If it is a Board build by yourself, you could do it with a GPIO-Pin and a transistor or something like this. Set GPIO high, ground the WP_Pin and write. Okay, this would only work if you are still designing the board. Or you put the EEPROM in a IC-Socket, then you can remove it and write it an a Breadboard. This is the reasoy why i prefer using EEPROMS in 8-pin DIP package. ^^

And just a questions since it seems I didnt got it, I just have to have a working overlay for the flash? Since I am working now with a dynamic overlay which I get working with the dtoverlay commandline command. And it works, so I just have to flash it, no further edits in the file to make it hat compatible??

Edit: maybe with a jumper cable from a ground gpio of the pi? but how could I hit the ground leg of the eeprom if it is tiny?

When you have a EEPROM in another package then DIP, you should try using probe-cable with a small end, or you can use a wire, solder it on the Pins and remove it after writing the EEPROM.

[dbwalker0min]

DO NOT DO THIS!

Update: I must have been on crack when I wrote this. I found out that all I needed to do was add the following line to the /boot/config.txt file:

Code: Select all

dtoverlay=i2c0

It worked perfectly well.

The insanity is below for reference...
─────────────────────────────
To access the HAT ID EEPROM, maybe it would be best to design the board in such a way that it can be connected to the main I2C bus. Then, it would be easier to access. I suggest something like the following circuit:

schematic.png (19.07 KiB) Viewed 42503 times

When the jumper is not in place, the internally pulled down WP signal also pulls down the select signal for the switches and the EEPROM is connected to the ID I2C bus (and is, of course, write protected). When the jumper is in place, the WP signal is set high and the switches select the main I2C bus so the device can be accessed normally. If there were an I2C address conflict (something else on the hat has the address 0b0101_000x), you could tie some of the address inputs to the WP line moving the EEPROM out of the way.

[logingit]

I tried connecting the eeprom to the Pi for flashing, https://logingit.com/how-to-install-pyt ... -with-pip/got stalled

[dbwalker0min]

Alternatively, to enable i2c0 (the Hat ID EEPROM bus), you can simply enable it on the command line with:

Code: Select all

sudo dtoverlay i2c0

The advantage of this is that you don't have to change the config.txt file and next time you boot, it is gone.