raspberrypi / hats

ADD-ON BOARDS AND HATs

N.B. THIS REPO HAS BEEN DEPRECATED. The new HAT+ EEPROM utilities can be found in our utils repo.

NOTE All references to GPIO numbers within this document are referring to the BCM283x GPIOs (NOT pin numbers on the Pi GPIO header).

Introduction

The Raspberry Pi boards with 40W GPIO headers (Model B+ and onwards) and have been designed specifically with add-on boards in mind. These boards support 'HATs' (Hardware Attached on Top). A HAT is an add-on board that conforms to the HAT specifications. HATs are not backward compatible with original Raspberry Pi 1 models A and B.

In October 2018 Raspberry Pi introduced the Micro-HAT (uHAT) specification. uHATs must follow all of the standard electrical HAT rules as laid our for normal HATs, but they have a smaller mechanical form factor as specified here

There are obviously a lot of add-on boards designed for the original model A and B boards (which interface to the original 26 way GPIO header). The first 26 pins of the 40W GPIO header are identical to those of the original models, so most existing boards will still work.

The biggest change with HAT add-on boards versus older boards designed for models A and B is that the 40W header has 2 special pins (ID_SC and ID_SD) that are reserved exclusively for attaching an 'ID EEPROM'. The ID EEPROM contains data that identifies the board, tells the Pi how the GPIOs need to be set up and what hardware is on the board. This allows the add-on board to be automatically identified and set up by the Pi software at boot time including loading all the necessary drivers.

While we cannot force anyone to follow our minimum requirements or HAT specification, doing so will make users lives easier, safer, and will make us more likely to recommend a product. Likewise if one of the minimum requirements is ignored we are unlikely to look on a product very favourably.

So why are we bothering with all this? Basically we want to ensure consistency and compatibility with future add-on boards, and to allow a much better end-user experience, especially for the less technically aware users.

Finally if you have any questions please head over to the forums to ask them.

New HATs / add-on boards basic requirements

If you are designing a new add-on board that takes advantage of the pins on the 40W GPIO header other than the original 26 then you must follow the basic requirements:

1. The ID_SC and ID_SD pins must only be used for attaching a compatible ID EEPROM. Do not use ID_SC and ID_SD pins for anything except connecting an ID EEPROM, if unused these pins must be left unconnected
2. If back-powering via the 5V GPIO header pins you must make sure that it is safe to do so even if the Pi 5V supply is also connected. Adding an ideal 'safety' diode as per the relevant section of the design guide is the recommended way to do this.
3. The board must protect against old firmware accidentally driving GPIO 6, 14 or 16 at boot time if any of those pins are also driven by the board itself.

Note that for new designs that only use the original 26 way GPIO header pins it is still recommended to follow requirement 2. if the board supports back-powering a Pi.

HAT requirements

A board can only be called a HAT if:

1. It conforms to the basic add-on board requirements
2. It has a valid ID EEPROM (including vendor info, GPIO map and valid device tree information).
3. It has a full size 40W GPIO connector.
4. It follows the HAT mechanical specification
5. It uses a GPIO connector that spaces the HAT at least 8mm from the Pi (i.e. uses spacers 8mm or larger - also see note on PoE header below)
6. If back powering via the GPIO connector the HAT must be able to supply a minimum of 1.3A continuously to the Pi (but ability to supply 2A continuously recommended).

Of course users are free to put an ID EEPROM on boards that don't otherwise conform to the remainder of the specifications - in fact we strongly encourage this; we just want things called HATs to be a known and well-specified entity to make life easier for customers, particularly the less technical ones.

NOTE that the Pi3B+ introduced a new 4-pin PoE header near the top-right corner mounting hole. Newly designed HATs that do not provide a connector for this header must avoid fouling it.

Design Resources

Before designing any new add-on board (HAT compliant or not) please read the design guide carefully.

For what to flash into the ID EEPROM see the ID EEPROM data format spec.

There are tools and documentation on how to flash ID EEPROMs here.

FAQ

Q: I want to keep shipping an existing board / ship a new board that only connects to the original 26W GPIO pins.

This is OK. You can't call it a HAT. If the board will back-power the Pi we recommend adding the safety diode as per requirement 2. of the basic add-on board requirements.

Q: I want to ship a board that attaches to the 40W GPIO header and covers ID_SD and ID_SC but does not include an EEPROM.

This is OK as long as it meets the basic requirements. You can't call it a HAT.

Q: I want to ship a board that has an ID EEPROM but does not conform to the remaining HAT specs.

This is OK as long as it also meets the basic requirements. You can't call it a HAT but you can say it supports GPIO autoconfiguration if the EEPROM contains valid vendor, GPIO map and DT blob information.

Q: I want to ship a HAT but the software for creating the EEPROM and/or DT blob isn't ready yet.

We expect all HATs to have a correctly programmed EEPROM, but bugs can happen, therefore make sure the EEPROM is user flashable. You will need to add some ability for a user to un-write-protect the EEPROM to (re-)flash it themselves as suggested in the design guide. Please provide instructions on your website / product packaging for how to reflash the board when any new image becomes available.

Q: I'm using the HAT mechanical spec but don't want to / can't add the cutout / slot for the display / camera flex.

This is OK and the board still conforms to the HAT specification. Some HATs will not be able to support the slot/cutout based on where the connectors and components must be placed (but it is recommended to support them if at all possible).

Q: I want to create a board that connects to the 'RUN' or 'PEN' header pin(s).

No problem but you can't call it a HAT. HATs are designed to be easy to use. Using the RUN pin requires a user to solder a header onto the Pi hence this is not something we wish to include in the HAT spec.

hats's Issues

EEPROM Signature backwards.

First 4 bytes of eep file should be 52 2D 50 69 they are currently 69 50 2D 52

HAT standoff recommendations

Please add some recommendations (w/ Mfgr No.) for the standoff length and style.

Error writing eeprom

I am having some issues programming the eeprom with the eepflash.sh script under Ubuntu Mate on a Pi 3. I have updated the pi, ensured that i2c is enabled and that the config setting "dtparam=i2c_vc=on" is present. I can run i2cdetect on bus 0 and see that it comes up at adress 50. However, when I run eepflash.sh script, I get the error "Loading of i2c-gpio dtoverlay failed". Do I need to add an entry in my config file for dtoverlay ? Or is this an issue with Ubuntu vs Raspian ?

EEPROM emulation.

Hi. I have a question and think that many people will have the same problem as well. I understand that if a HAT does not not have its own micro - EEPROM is needed. But at the moment I develop couple of HATs with their own ARM uCs. I can emulate the full EEPROM functionality using uC I2C interface & flash memory. Can I do it, or I still need a separate EEPROM IC? Timing is not an issue as the uC is ready much earlier than RPI starts reading the content form it.

eepflash.sh gives an error "./eepflash.sh: 6: ./eepflash.sh: Syntax error: "(" unexpected"

When running eepflash.sh I get an error:
./eepflash.sh: 6: ./eepflash.sh: Syntax error: "(" unexpected

Removing the 'function' keyword seems to cure it.

eepmake: How to access the flashed custom file from user space?

After flashing a custom file to the ID EEPROM, how do you actually access it later from user space? I thought it would be in /proc/device-tree/hat/..., but it is not.

Dimension error in uhat-board-mechanical.pdf

The board overall dimension is called out as 30.5mm, this does not match the board shape of the rpi zero of 30mm. Also if you add up the the dimension of mounting holes to edge of board (3.5mm + 3.5mm) plus dimensioned space between hole centers of 23mm it does not add up to 30.5mm. This makes me pretty confident that the 30.5mm dimension is incorrect.

If changing the drawing, it would also be nice to indicate where pin 1 of the 40 pin header is.

Inconsistent flags in eepflash.sh

The 'help' option has the usual convention of a single-dash (-h) for the one-letter argument, and a double-dash (--help) for the longer version of the argument.

But then the read, write, file and type options use a single-dash for both the short and long arguments, which seems a bit unusual? :-/

CRC format

The documentation states that each atom uses "CRC-16-CCITT" as the crc16 format.

  2       crc16       CRC-16-CCITT of entire atom (type, count, dlen, data)

According to http://srecord.sourceforge.net/crc16-ccitt.html and http://crcmod.sourceforge.net/crcmod.predefined.html, CRC-16-CCITT has the following attributes:

Truncated polynomial = 0x1021
Initial value = 0xFFFF
Input data is NOT reflected

When looking at the code for calculating the CRC in eeptypes.h, I see:

#define CRC16 0x8005

....
uint16_t getcrc(char* data, unsigned int size) {
...
// item c) reverse the bits

This would suggest that the polynomial is actually 0x8005 and the data is reversed, which corresponds with a plain CRC-16.

Repo Contents Licence - Open Source? Public Domain? Other?

There's no mention of a licence for the contents of this repo that I can find, being the rPi Foundation, I assume this is intended to be either under an open source licence or within the public domain, but I figured I should check, and request a LICENCE file is added to the repo.

VSS/VCC could be confusing to noobs.

The ID EEPROM is an old Catalyst part and the datasheet also uses VCC while claiming to be CMOS with not a collector in sight.
Suggest changing to VDD.
(Yes, I know complementary has PFET source, and it's left over from NMOS, but that's the convention.)

Dimension error in hat-board-mechanical.pdf

If the HAT is 56.5mm wide (as shown on the drawing), the distance from hole center to edge should be 4mm, not 3.5mm. If it's 56mm wide (as mentioned as an option in the text), the hole distance is correct, though.
Pi 3 and 4 have 56mm wide boards (don't know about older models) , so maybe the 56.5mm option should just be dropped altogether?

Spec validity for Pi 2 and 3

well... any information on this? Readme says B+, but what about 2 and 3?

HAT definition applies to A+ as well as B+ (Right?)

hats/Readme.md makes no mention of the Raspberry Pi model A+, only the B+.
I understand that the HAT definition applies to the A+ model too, so Readme.md ought to reflect this.
Perhaps the same is true of the newer Pi 2 as well?
Thanks,
JC.

Change Request: Add optional previsions to the Spec for stacking HATs

There are use cases and there is value in the ability to stack multiple HATs.
As standards should not be written in stone, but ought to evolve over time, it should be appropriate for members of the community to develop (through backwards compatible extensions) methods for the discovery and configuration of multiple stacked HATs. aka "HAT++"???

To that end I would invite the HATs contributors and the community at large to discuss [within this issue] how such a stacking extension could be developed and a path for that extension to be included in a revision to the original HAT specification.

Cannot create /sys/class/i2c-adapter/i2c-0/new_device: Directory nonexistent

Hello guys,
I'm working on a hat and have stumbled upon a problem with EEPROM.
When I try to access the EEPROM on B+ with latest Raspbian here's what I get:

sudo ./eepflash.sh -r -f=dump.bin -t=24c32
This will disable the camera so you will need to REBOOT after this process completes.
This will attempt to write to i2c address 0x50. Make sure there is an eeprom at this address.
This script comes with ABSOLUTELY no warranty. Continue only if you know what you are doing.
Do you wish to continue? (yes/no): yes
./eepflash.sh: 116: ./eepflash.sh: cannot create /sys/class/i2c-adapter/i2c-0/new_device: Directory nonexistent
Reading...
dd: opening `/sys/class/i2c-adapter/i2c-0/0-0050/eeprom': No such file or directory
Error doing I/O operation.

The EEPROM is 24c32 and it is connected to ID_SC and ID_SD pins, 3.9k pullups are in place too.
I'm sure that chip is fine because when I connect it to I2C_SDA and I2C_SCK pins it's accessible by the address 0x50 on i2c-1.
Any ideas what might be wrong?

error doing i/o operation

How may be identified more than one HAT board when stacked?

How may I2C read more than one HAT EEPROM if there is only one fixed 0x50 I2C address?
Even there is unique UUID, the hardware EEPROM address allows to read only one EEPROM.
If stacked two boards, the address collision results in global communication error and no one is recognized.

SCL/SDA mixup in designguide.md

Within the set of pins available on the GPIO header, ID_SC and ID_SD (GPIO0/SCL and GPIO1/SDA) are reserved for board detection / identification.

According to https://www.raspberrypi.org/documentation/usage/gpio/ it should be:

Within the set of pins available on the GPIO header, ID_SC and ID_SD (GPIO0/SDA and GPIO1/SCL) are reserved for board detection / identification.

In addition I would like to propose to also add the pin numbers 27/28 to be more generic.

/sys/class/i2c-adapter/i2c-0 folder missing

When running eepflash I get the following error.
eepflash.sh: line 116: /sys/class/i2c-adapter/i2c-0/new_device: No such file or directory

looking in the file system the /sys/class/i2c-adapter/i2c-0 folder is missing.
This was encountered on a pi2.

No documentation for the "type" argument expected by eepflash.sh

If a 'type' (-t) argument isn't supplied to eepflash.sh then it prints "You need to set eeprom type. Try -h for help."
However the help text just says " -t=eeprom_type: eeprom type to use" which doesn't provide any hints as to what should be specified for "eeprom_type".

0x0004 Atom

Hi,

I've got the rest of the EEPROM on a HAT I'm developing fully figured out but was wondering about the section mentioned about storing manufacturer data.

What can we store here? Example python code? Readme?

If we can store this type of stuff how do we? Is it as simple as adding the custom file to the eeprom make command?

Unable to specify GPIO as output, driven high.

# SPI Chip Enables

# microcontroller
setgpio   8     OUTPUT    UP
# gyro
setgpio   7     OUTPUT    UP
# accelerometer
setgpio   5     OUTPUT    UP

Doesn't do what one might expect; it configures these GPIOs as outputs, with the weak pullup enabled.. with the IO driven down hard.

When used for SPI chip enables, this is super bad, because the default of driving the pin down low means the slaves can fight on the MISO pin.

Ideally there would be a way to tell the bootloader to forcefully drive these pins high ASAP.

Link to additional device tree documentation?

Is it worth adding a link from https://github.com/raspberrypi/hats/blob/master/devicetree-guide.md to http://www.raspberrypi.org/documentation/configuration/pin-configuration.md ?

Not geting /proc/device-tree/hat

I make a shield with the serial eprom flashed with my device description based on the provided tools. After rebooting, configuration of the gpio are not taken into account, in /proc/device-tree I do not see any HAT sub-directory...
Why ?
kernel : 3.18.7-v7+
in config.txt, i2c_vc is on.

eepflash.sh when using i2c-gpio on Pi4 uses i2c bus 7 not bus 3

Since the Pi4 has multiple i2c buses the first available bus for i2c-gpio is bus 7.

Hat Mechanical Specification updated for RPi Zero

Could the HAT mechanical specification be updated for the Raspberry Pi Zero and Zero W (i think they would be the same). I have a HAT I have designed, but I cannot call it a HAT due to no Mech Spec for the Zero.

eepflash.sh not compatible with dd 8.23 (no status=progress)

In eepflash.sh the lines calling dd contain 'status=progress'.

This option is not compatible with dd 8.23, which is by default on my setup (Linux raspberrypi 4.4.50-v7+), since the 'progress' option has only been introduced as from dd 8.24.
apt-get update doesn't update dd to 8.24, so the script needs to be corrected.

The solution has been to replace 'status=progress' with 'status=none', as per the following patch.

In addition to this (since the above generates an error), I noticed that eepflash.sh is not robust to such errors: It locks the file but doesn't free it in case an error occurs (The eeprom appears with 'UU' when using i2cdetect -y 0).

The solution here consists in moving the 'closing' code before returning in case of an error.

I attach the patch I applied to get it to work.

eepflash_status_process.patch.gz

Question: Changes to power requirements for RPi 4?

When the RPi4 was released I remember reading that one of the reasons for changing the power connector to USB-C was to get a little more available power. If I want to make a HAT that supplies (+5VDC) power to an RPi 4, how much current does it need to be able to source? Is it still about 2A or does the new model need more?

eepmake: eep file generate with wrong informations (multiple custom file)

When an eep file is generate with multiple custom file the generated eep file contain wrong information. The UUID is not the one set in the eeprom_settings.txt thats the same story with the VendorId and the ProductId.
After several test I found that the UUID change a little bit with 2 customs files and the UUID change a lot with 3 custom files.

Licence missing from the project

Hi All,
I was looking for the specifications but I cannot find any reference to licence or IP of the HATS specifications/requirements, EEPROM design requirements, etc.

Could you please clarify and also add it to the project page?

Thanks!

How can I create /proc/device-tree/hat/custom_0

How can I create such a node ( /proc/device-tree/hat/custom_0 )?
which contains additional info.

RPi2 and HATs

I am developig a HAT and it works perfectly with B+ but with RPi2 overlay from EEPROM is not loaded. The same overlay can be loaded from /boot/overlays with dtoverlay option in config.txt. Any advice?

Kicad project & routing for Hats

I create a cicada project with Hat specifications ; it has been used to design 2 hat cards already. It is public and BSD licences ; eventually this project could refer it : https://github.com/disk91/hat-design

I2C pullups.

The "raspberry pi R2" schematics show a pullup of 1.6k on GPIO0 / GPIO1 . I checked, and they are still there on the "B+".

Why specify a 2k2 pullup on the "hat"? You risk say a camera no longer working if the current on the bus line starts to exceed the capability of the pin involved.

As a matter of fact, as currently specified you're exceeding specs for the recommended eeprom:
At 3.3V there is 2.06mA flowing through the 1k6(*) on the Raspberry Pi, 1.5mA through the 2k2 on the hat, which adds up to 3.5mA which exceeds the VOL spec at 3.0mA.....

And this is even before we start stacking hats... The subtle "top hat" is not going to change that every hat would have its own pullup....

Oh, I'm convinced it will work, but better to stay within spec...

(*) Possibly replaced by 1k8 on the B+?

GPIO header

Could you add some link to find the 10-12mm GPIO header, they are really hard to find

No run/reset connector on mechanical drawings for RPi 3 B+

No run/reset connector on mechanical drawings for RPi 3 B+

"Device Tree Usage" link results in 404

The "device tree usage" link in devicetree-guide.md results in a 404. I quickly search the devicetree.org website for the new link, but couldn't find the page.

RPI does not boot if HAT EEPROM is corrupted

I've seen a problem with a board where the EEPROM content wasn't written correctly. With older 3.x kernels the board boots, but not with the latest kernel/firmware. Is there any kernel parameter to ignore the ID PROM contents? This needs to be only temporary to write the correct EEPROM contents.

eepflash.sh doesn't check IO status correctly

Looks like the script is missing a rc=$? after each of the dd lines?

And the part that prints "You need to be root" seems to be redundant as root-access is already checked for earlier in the script?

UUID creation logic will not work after 9999

If the bar code serial of any DCU crosses 9999 then the UUID creation and writing to EEPROM logic will not work as it is currently configured for 4 digit bar code

eepflash.sh update cannot find eeprom in system folder

Hello,

I am having difficulties using eepflash.sh to flash an eep file. I was previously using a Raspberry pi zero W running raspian Stretch and your code from 24 October 2018. I was able to flash my device without issue. After pulling the new repository (the most recent from 2020), my pi now returns this string of errors:

pi@raspberrypi:~/Desktop/EEPROM/hats/eepromutils $ sudo ./eepflash.sh -w -f=K9JR-BT-eeprom_settings.eep -a=50 -t=24c32 This will attempt to talk to an eeprom at i2c address 0x50 on bus NOT_SET. Make sure there is an eeprom at this address. This script comes with ABSOLUTELY no warranty. Continue only if you know what you are doing. Do you wish to continue? (yes/no): yes Expected I2C bus (i2c-9) not found. ./eepflash.sh: 140: ./eepflash.sh: cannot create /sys/class/i2c-adapter/i2c-NOT_SET/new_device: Directory nonexistent Writing... dd: failed to open '/sys/class/i2c-adapter/i2c-NOT_SET/NOT_SET-0050/eeprom': No such file or directory Closing EEPROM Device. ./eepflash.sh: 164: ./eepflash.sh: cannot create /sys/class/i2c-adapter/i2c-NOT_SET/delete_device: Directory nonexistent Error doing I/O operation.

I followed the setup of the repository on my local machine but this did not help. Would you be able to offer any insights as to why the updated code fails on my device? Do I need to make any changes to my Raspberry Pi settings? Attempting to do an overlay like in the instruction s(to set i2c-9) also fails.

Note: I also tried the code (both old and new) on the new Raspberry pi OS running on a raspberry pi Zero and that also returned similar errors.

Please let me know if you require more clarity on the nature of my problem. I will be happy to give you more information if needed.

Add missing fields to eepdump

we want all the raw fields in the dumper so we can see them, e.g. vendor and product string lengths are missing. raw CRCs are missing. Atom count missing.

HAT not compatible with official RPi enclosure

is there is new HAT spefication? Because any HAT design to the old one would not fit into the RPi official enclosure :(

EEPROM file. Hat is using different pins depending in the configuration

Hi. My hat is connects to the RPi via SPI. It uses only one only four pins - but can be configured to use two SPIs and 5 CS signals. The board does not know what SPI port or which CS signal was chosen. Should I mark all 9 lines as used by the hat?

GPIO seems not been set after hat configuration

The hat entry is correctly fill with the eprom content but the the GPIO seems to not be set correctly as I choose to have some Pulled UP and the seems to stay DOWN. Any idea to debug ?

PoE

Fixes:

• Delete PoE comment from uHat
• Add PoE comment to Hat
  Suggestions:
• Move the keep out area on the uHat specification to actually cover the RUN/TV connectors
• Add the RUN connector location to the Hat specification
  Curious:
• Why does the PoE location on the Hat specification not match the PoE location on the RPi (or PoE Hat for that matter)?

Add automatic GUID creation

Provide option for eepmake to automatically create and fill in the GUID field (it should also spit out the GUID to the console for logging purposes).
Easiest way might be to detect a zero GUID in the input text file and replace this automatically (as we always want boards to have a GUID).

Multiple overlays and additional parameters in one HAT config

I need to have several overlays in one HAT EEPROM config file. And more I need to set some additional parameters for the specific overlay. Any idea how to do so? I've tested everything but no success.
To have some config in the HAT and the rest in the config.txt file is no the target.

Remove confusing mention of stacking HATs?

https://github.com/raspberrypi/hats/blob/master/eeprom-format.md#vendor-info-atom-data-type0x0001 says "It protects against the case where a user accidentally stacks 2 identical HATs on top of each other - this error case is only detectable if the EEPROM data in each is different." and it seems that this has caused some confusion - http://www.raspberrypi.org/forums/viewtopic.php?f=100&t=85786

Now that HATs are specifically defined to be non-stackable, maybe this sentence should be revised?