Hat tv2

[beniroquai]

Hey @christiankuttke, these are suggestions for the docs for the HAT - they are mostly AI generated and I know you don't like that but maybe this is a first start for the real docs. I need help with the pinout and I gues @ethanjli needs input for the I2C-based setting of the high-current mode ;)

[Copilot]

Pull Request Overview

This PR adds comprehensive technical documentation for the openUC2 Raspberry Pi HAT+ v2 (FRAME Controller), providing detailed specifications, integration guides, and bring-up procedures for the hardware.

Key Changes

• New 496-line technical documentation covering HAT+ v2 hardware specifications
• Detailed electrical architecture, communication interfaces, and safety features
• Complete ESP32 pinout configuration code for firmware integration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Section numbering is inconsistent. Section 18 appears after section 16.3, skipping section 17. This should be renumbered to '### 16.4 Pinout' to maintain sequential ordering within the appendix.

Suggested change

	### 18 Pinout
	### 16.4 Pinout

[Copilot]

Trailing whitespace after the value '1'. Remove the extra space for consistency with other macro definitions.

Suggested change

	#define BTHID 1
	#define BTHID 1

[christiankuttke]

I got to line 21 correcting its errors and irrelevancies before I got pissed off.

The generated document is very long and unfocused. It repeats a bunch of stuff multiple times, without extra information. It gets stuff wrong and imprecise, and of course it talks about not-implemented functions. Then, the name for the document is wrong - it should follow Hardware revisions and the current one is Rev. D.

What should I do with this?

• Do you like the structure and verbosity of the generated document? Then I should review and correct the whole rest (1-2 weeks of hateful work).
• Should I make a document from scratch? I need to know who that's for, so how detailed I should explain the capabilities (and what categories - pinout, I2C, SPI, jumpers, jacks/interfaces, power capabilities, design requests/it fulfilling functions that have been requested or found necessary through prototyping/iteration)

I'll scroll through the document some more.

[christiankuttke]

Have you got communiation with the EEPROMs working with the bodge? Because I haven't. I'll try communicating with the EEPROMs some more.

[beniroquai]

I absolutely get your point! We can rewrite the docs from scratch focussing on what's most relevant. For me it's crucial:

• Pins for I2C
• temperature sensor? Which one?
• How does the buzzer work?
• How can I detect if the emergency stop was hit?
• Is there a way to switch off 12V from the esp/raspi?
• which solder jumpers are worth bridigng so that I can see CAN activity and have terminators
• How can we activate high current mode in a reproducible way (in best case wihtout too much work, automated..)

The pinout for the v2 you have provided I guess in a PR on the UC2-ESP repo.

[ethanjli]

Here's my wishlist from the ImSwitch OS side:

• For every GPIO-related line of https://github.com/openUC2/rpi-imswitch-os/blob/main/os-build/platform-hardware/config.sh I would like to be able to add a code comment justifying its inclusion in the config.sh script, with a link to somewhere in the hardware docs as part of the justification (e.g. since we're enabling the serial port and serial port console functionalities on the RPi GPIO, I need to be able to point at the hardware documentation to explain why we're enabling those functionalities)
• I also need to know enough about how the GPIO header is used that I could explain with confidence how our config settings doesn't cause any interference with pins used by the openUC2 HAT+ (e.g. since we're enabling the serial port and serial port console functionalities on the RPi GPIO, I need to be able to point at the hardware documentation to show that those functionalities don't conflict with any GPIO pins needed by the HAT+)
• I would like to have an overview of all hardware-related functionalities on the HAT which the OS may need to support (e.g. EEPROM), and necessary details (e.g. GPIO header pin numbers, and optionally also Broadcom pin names and Broadcom pin functions) for correctly integrating [any necessary] software drivers with our HAT and for testing those integrations.
• I would like to have a description of each workaround/bodge which may be needed to enable a certain functionality (e.g. EEPROM) on this revision of the HAT+ design, so that I can determine which bodges are and aren't on the boards I have on hand, and so that I can determine which bodges I don't need.
• I would like to have written documentation of all data communication interfaces on the HAT+ (but especially interfaces which the RPi may interact with), and what each interface is used for, so that I can have a reasonable system-level understanding on the board even though my memory is very unreliable
• I would like to know about what the buttons on the HAT+ do, and how I should use them correctly, and when each button may need to be used
• I would like to know how to interpret the appearances of the various LEDs on the HAT+
• I would like to know about any indicator LEDs (or buzzers or other things) which have been provisioned on the HAT+ for displaying state from the RPi (if such LEDs exist), and all information that would be necessary for me to implement/integrate drivers for those indicator LEDs (e.g. GPIO header pin numbers, and optionally also Broadcom pin names and functions). If the indicator devices are all controlled from the ESP32, then Ethan-who-maintains-ImSwitch-OS doesn't need to know this information, but Ethan-who-may-be-asked-to-help-maintain-the-ESP32-firmware will need to know this information.
• I will need to know information about relevant hardware subsystems and interfaces (e.g. pins) needed for implementation of https://www.notion.so/Report-laser-interlock-status-2774e612c78a80cca9aafa79c0c3044d?source=copy_link .

[beniroquai]

@christiankuttke would you mind having a look at the configuration file Ethan created? Does it look complete to you?

[ethanjli]

@christiankuttke would you mind having a look at the configuration file Ethan created? Does it look complete to you?

Are you referring to the config file snippet we added and tested together in a pair-programming session in openUC2/rpi-imswitch-os#48 ?

[beniroquai]

@christiankuttke the colour code is: camera in opto pin 2 => yellow, camera gnd opto pin 5 => white.
It's soldered to the SMA connector. Can you please document that in the HATv2
More info https://github.com/openUC2/TechnicalDocs-openUC2-FRAME/issues/134