Touch display changes #3121

jehlers42 · 2023-09-17T22:38:38Z

No description provided.

jehlers42 · 2023-09-17T22:53:50Z

@aallan Continued from #3119...

I've expanded on sections and did my best to incorporate most of the troubleshooting and tips into the main page. Didn't modify the troubleshooting page itself yet.

It doesn't feel like every item in the troubleshooting section can have a new home, but I'm also not sure those items are entirely necessary? I'm also not sure the new "X11" section I added is the best way to handle those specific items. I thought about adding them to the Legacy section instead. Thoughts?

jehlers42 · 2023-09-19T00:55:47Z

Okay, ready for review on this one. Still not 100% sure on the best way to handle explaining the X11-only features (if we even need to at all).

aallan · 2023-09-19T08:36:06Z

documentation/asciidoc/accessories/display/display_intro.adoc

 | Swap X and Y coordinates
 |===

 === X11-only features


Should explain why you might be running X11. Either older Pi hardware — although in time Bookworm should be moving to Wayland for all Pi hardware — or an older version of the OS.

I'm not sure if labelling these as "X11-only features" is the angle we want to go for here (but this is obviously a decision for @aallan to make). IIRC these are features which we also want to see in Wayland (in future), but which simply haven't been implemented yet. 🤷 😕

For stuff that only works in X11 or differently in X11 and not in Wayland, or only in a previous version of the OS, as I mentioned before, I want these hared off into a separate NOTE block. Preferably a short standalone, minimally documented one with just the incantations not masses of explanatory text around it.

After throwing it in a note block I didn't like its current location. Moved it to the front of the Legacy section instead. Let me know if that works better.

documentation/asciidoc/accessories/display/display_intro.adoc

aallan · 2023-09-19T08:52:14Z

documentation/asciidoc/accessories/display/display_intro.adoc

+===== Provide power with Raspberry Pi

-=== Physical Installation
+To power the Touch Display using a Raspberry Pi, you need to connect two jumper wires between the xref::/../../computers/raspberry-pi.adoc#gpio-and-the-40-pin-header[Raspberry Pi's GPIO] and the GPIO pins on the display's PCB.


Which pins?

documentation/asciidoc/accessories/display/display_intro.adoc

lurch · 2023-09-19T14:04:45Z

documentation/asciidoc/accessories/display/display_intro.adoc

+
+There are two options available to provide power to the Touch Display: using the Raspberry Pi's GPIO, or a separate power supply and micro USB cable. 
+
+===== Provide power with Raspberry Pi


"Provide power with Raspberry Pi" -> "Provide power from the Raspberry Pi" ?
(perhaps it's just me, but "with" sounds strange here)

Changed to "Provide power through the Raspberry Pi"

documentation/asciidoc/accessories/display/display_intro.adoc

lurch · 2023-09-19T14:11:02Z

documentation/asciidoc/accessories/display/display_intro.adoc

+
+==== Powering the Touch Display
+
+There are two options available to provide power to the Touch Display: using the Raspberry Pi's GPIO, or a separate power supply and micro USB cable. 


IIRC powering the Display from the Pi (via the GPIO pins) is considered the preferred option, so perhaps that should be mentioned here?

Added a sentence saying we recommend that method. Let me know if it looks okay.

documentation/asciidoc/accessories/display/display_intro.adoc

aallan · 2023-09-20T09:48:08Z

documentation/asciidoc/accessories/display/legacy.adoc

 == Legacy Support

-NOTE: These instructions are for the original Raspberry Pi 1 Model A and B boards only. You can identify an original board as it is the only model with a 26-pin GPIO header, all other models have the now-standard 40-pin connector.
+[NOTE]


This is a big NOTE block, should probably be at the end rather than right at the start of the section.

OTOH, if this was moved to the end of the Legacy section, people might think that the "are for the original Raspberry Pi 1 Model A and B boards only" disclaimer applies too? 🤷‍♂️

That was my thinking on it, @lurch. Otherwise it'd likely need a heading to separate it from the old hardware instructions and, well, that sort of negates the idea of a note block.

documentation/asciidoc/accessories/display/display_intro.adoc

documentation/asciidoc/accessories/display/legacy.adoc

lurch · 2023-09-20T12:53:40Z

documentation/asciidoc/accessories/display/legacy.adoc

+sudo apt install matchbox-keyboard
+----
+
+Add the following to `/etc/X11/xorg.conf` enable right click emulation:


Missing "to" before "enable".
@aallan Should "right click emulation" be "right-click emulation" ?

@aallan Should "right click emulation" be "right-click emulation" ?

Yes.

Okay so this brings up something I've noticed where "right-click" hasn't been properly hyphenated in a handful of other pages. With your permission, I can do a mass find-and-replace to take care of those and make it part of this PR since, admittedly, it's been bothering me quite a bit.

@jehlers42 https://github.com/raspberrypi/style-guide/blob/master/style-guide.md says right-click, so that's probably the green-light you need 🚦 😃
(although probably "cleaner" to do it as a separate PR, rather than bundling it into this PR)

documentation/asciidoc/accessories/display/legacy.adoc

jehlers42 · 2023-09-20T17:00:52Z

More changes made, some open comments/questions/acceptances still.

aallan

Not there yet.

documentation/asciidoc/accessories/display/display_intro.adoc

aallan · 2023-09-20T18:08:07Z

documentation/asciidoc/accessories/display/display_intro.adoc

+The Touch Display will function with all models of Raspberry Pi. Although, the earliest Raspberry Pi models, which lack appropriate mounting holes, require additional mounting hardware to fit the stand-offs on the display PCB.

-The DSI display is designed to work with all models of Raspberry Pi, however early models that do not have mounting holes (the Raspberry Pi 1 Model A and B) will require additional mounting hardware to fit the HAT-dimensioned stand-offs on the display PCB.
+You can mount a Raspberry Pi to the back of the Touch Display using its stand-offs and then connect the appropriate cables between each device, depending on your use case. You can also mount the Touch Display in a separate chassis if you have one available. The connections remain the same, though you may need longer cables depending on the chassis you use.


"appropriate"? There are in-appropriate cables? What cables?

Used it in the sense to imply different cables. Data and power cables would be appropriate, in this case. Will reword though.

Forgot to reword it in the latest commits, but still plan on doing so. There was just...a lot to get through.

Perhaps "appropriate" -> "necessary"? 🤷‍♂️

documentation/asciidoc/accessories/display/display_intro.adoc

documentation/asciidoc/accessories/display/legacy.adoc

aallan · 2023-09-20T18:36:36Z

documentation/asciidoc/accessories/display/display_intro.adoc

 image::images/GPIO_power-500x333.jpg[Image of Raspberry Pi connected to the Touch Display, width="70%"]

-Connect one end of the ribbon cable to the `RPI-DISPLAY` port on the Touch Display PCB so the side with the silver or gold pins faces away from the display. Then connect the other end of the ribbon cable to the `DISPLAY` port on the Raspberry Pi. The pins should face inward, towards the Raspberry Pi.
+Connect one end of the ribbon cable to the `RPI-DISPLAY` port on the Touch Display PCB. The silver or gold contacts should face away from the display. Then connect the other end of the ribbon cable to the `DISPLAY` port on the Raspberry Pi. The contacts on this end should face inward, towards the Raspberry Pi.


Not a ribbon cable.

Current docs refer to it as such:
"how to connect both the data (ribbon cable)"
"take extra care when attaching the ribbon cable to ensure it is the correct way round"

What else would we call it?

Saw comment from earlier. Will update this article, but should we double-check all our references to ribbon cables since I'm pretty sure the camera docs use that terminology as well.

Wikipedia says "FFC is a miniaturized form of ribbon cable, which is also flat and flexible." which probably explains why the terms are sometimes used interchangeably.

lurch · 2023-09-21T08:38:03Z

documentation/asciidoc/accessories/display/display_intro.adoc

+=== Touchscreen orientation

-`dtoverlay=rpi-ft5406,touchscreen-swapped-x-y=1,touchscreen-inverted-x=1`
+You also have the option to change the rotation of the active touchscreen area independently of the display itself by adding a `dtoverlay` instruction in the xref:../computers/config_txt.adoc[`/boot/firmware/config.txt`] file, as in the following example:


Small niggle, but does "active touchscreen area" imply that there's also an "inactive touchscreen area" ? 🤔

lurch · 2023-09-21T08:55:01Z

This PR doesn't have a directly-associated Bookworm issue, but I'm labelling this as bookworm as that's the branch that it's modifying.

Touch display changes

681ac02

jehlers42 mentioned this pull request Sep 17, 2023

Add placeholder image and update instructional text #3119

Closed

Expanded article

24aefe1

jehlers42 added needs discussion documentation labels Sep 17, 2023

jehlers42 requested a review from aallan September 17, 2023 22:53

This was linked to issues Sep 18, 2023

Touch Display installation needs better instructions #3007

Closed

Ambiguity about powering the Touch Display #2977

Closed

Content changes, removed troubleshooting

03d63fb

jehlers42 marked this pull request as ready for review September 19, 2023 00:55

aallan reviewed Sep 19, 2023

View reviewed changes

aallan suggested changes Sep 19, 2023

View reviewed changes

aallan added waiting for revisions Waiting for the OP to make revisions and removed needs discussion labels Sep 19, 2023

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 19, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

Edits based on feedback

e342a99

aallan suggested changes Sep 20, 2023

View reviewed changes

lurch reviewed Sep 20, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 20, 2023

View reviewed changes

documentation/asciidoc/accessories/display/display_intro.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 20, 2023

View reviewed changes

documentation/asciidoc/accessories/display/legacy.adoc Outdated Show resolved Hide resolved

lurch reviewed Sep 20, 2023

View reviewed changes

documentation/asciidoc/accessories/display/legacy.adoc Outdated Show resolved Hide resolved

More feedback changes

5068feb

aallan suggested changes Sep 20, 2023

View reviewed changes

jehlers42 added 2 commits September 20, 2023 11:29

Severe language removal

7ee790a

Pins > contacts for ribbon cable

8021112

aallan reviewed Sep 20, 2023

View reviewed changes

jehlers42 added 2 commits September 20, 2023 14:04

Additional changes

4ee6737

Fix config.txt location

8345d9d

lurch reviewed Sep 21, 2023

View reviewed changes

lurch added the bookworm 🐛 Issue with Bookworm label Sep 21, 2023

aallan approved these changes Sep 23, 2023

View reviewed changes

aallan merged commit 0fa704b into bookworm Sep 23, 2023

aallan deleted the display branch September 23, 2023 04:20

aallan removed the waiting for revisions Waiting for the OP to make revisions label Sep 23, 2023

aallan mentioned this pull request Sep 25, 2023

Touch Display installation needs better instructions #3007

Closed


		There are two options available to provide power to the Touch Display: using the Raspberry Pi's GPIO, or a separate power supply and micro USB cable.

		===== Provide power with Raspberry Pi


		==== Powering the Touch Display

		There are two options available to provide power to the Touch Display: using the Raspberry Pi's GPIO, or a separate power supply and micro USB cable.

Touch display changes #3121

Touch display changes #3121

Uh oh!

Conversation

jehlers42 commented Sep 17, 2023

Uh oh!

jehlers42 commented Sep 17, 2023

Uh oh!

jehlers42 commented Sep 19, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jehlers42 commented Sep 20, 2023

Uh oh!

aallan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment