martinlbb
Posts: 4
Joined: Thu Jun 20, 2013 3:32 pm

STICKY: HOWTO: Raspi HAT EEPROM and device-tree

Wed Apr 22, 2015 1:46 pm

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 668 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
Posts: 6
Joined: Wed Jul 31, 2013 9:45 pm

Re: Howto: Raspi HAT EEPROM and device-tree

Tue Mar 08, 2016 10:06 pm

Splendid!

User avatar
karrika
Posts: 952
Joined: Mon Oct 19, 2015 6:21 am
Location: Finland

Re: Howto: Raspi HAT EEPROM and device-tree

Wed Mar 09, 2016 4:58 am

Thank you for a very nice tutorial.

PhilE
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 1419
Joined: Mon Sep 29, 2014 1:07 pm
Location: Cambridge

Re: Howto: Raspi HAT EEPROM and device-tree

Mon Mar 14, 2016 8:40 pm

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
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 4604
Joined: Wed Dec 04, 2013 11:27 am
Location: ZZ9 Plural Z Alpha, aka just outside Cambridge.

Re: Howto: Raspi HAT EEPROM and device-tree

Sat Mar 19, 2016 7:04 pm

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.
Software Engineer at Raspberry Pi Trading. Views expressed are still personal views.
Please don't send PMs asking for support - use the forum.
I'm not interested in doing contracts for bespoke functionality - please don't ask.

PhilE
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 1419
Joined: Mon Sep 29, 2014 1:07 pm
Location: Cambridge

Re: Howto: Raspi HAT EEPROM and device-tree

Sat Mar 19, 2016 8:31 pm

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
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 4604
Joined: Wed Dec 04, 2013 11:27 am
Location: ZZ9 Plural Z Alpha, aka just outside Cambridge.

Re: Howto: Raspi HAT EEPROM and device-tree

Sat Mar 19, 2016 9:56 pm

PhilE wrote: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.
Software Engineer at Raspberry Pi Trading. Views expressed are still personal views.
Please don't send PMs asking for support - use the forum.
I'm not interested in doing contracts for bespoke functionality - please don't ask.

musskopf
Posts: 5
Joined: Mon Nov 02, 2015 9:18 am

Re: Howto: Raspi HAT EEPROM and device-tree

Wed Mar 30, 2016 5:46 am

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
Posts: 72
Joined: Fri Sep 23, 2016 10:02 pm
Location: Inside my Pi

Re: Howto: Raspi HAT EEPROM and device-tree

Sun Apr 30, 2017 9:11 pm

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

FeroxCannibal
Posts: 36
Joined: Fri Apr 28, 2017 8:00 am

Re: STICKY: HOWTO: Raspi HAT EEPROM and device-tree

Mon Aug 28, 2017 6:09 pm

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
Posts: 2
Joined: Tue Oct 10, 2017 9:38 pm

Re: STICKY: HOWTO: Raspi HAT EEPROM and device-tree

Fri Oct 13, 2017 4:30 pm

FeroxCannibal wrote:
Mon Aug 28, 2017 6:09 pm
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. ^^
FeroxCannibal wrote:
Mon Aug 28, 2017 6:09 pm
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.

Return to “Advanced users”

Who is online

Users browsing this forum: No registered users and 6 guests