From 384dd78057d763d1bc620b9a64c62b29d8024c37 Mon Sep 17 00:00:00 2001 From: Corey Vixie Date: Sun, 29 Mar 2020 12:18:37 -0700 Subject: [PATCH] Add documentation --- README.md | 57 +++++++++++++++++++ platforms/beaglebone/README.md | 88 +++++++++++++++++++++++++++++ platforms/beaglebone/docs/Pinmux.md | 61 ++++++++++++++++++++ 3 files changed, 206 insertions(+) create mode 100644 README.md create mode 100644 platforms/beaglebone/README.md create mode 100644 platforms/beaglebone/docs/Pinmux.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f61f92 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# Sitronix ST7701S SPI/RGB Display Driver + +**⚠️ This is a work in progress** + +This is a basic display driver for displays based on the Sitronix ST7701S, using SPI for command and control and parallel RGB for video data. It currently targets ARM single-board computers, but may be able to be compiled for other architectures. + +## Development Host Setup + +Install the following software: + +- [Vagrant](https://www.vagrantup.com/downloads.html) +- [Virtualbox 6.0](https://www.virtualbox.org/wiki/Download_Old_Builds_6_0) (6.1 is incompatible with Vagrant as of late 2019) + +## Development Target Setup + +You will need a dedicated single-board computer to target: + +- Beaglebone Black ([Setup Docs](./beaglebone)) +- Raspberry Pi (Untested) + +### Software + +The following programs are required on all development targets: + +- `cpp`: Used to build the Device Tree Overlay +- `dtc`: Used to build the Device Tree Overlay + +These are optional, but helpful: + +- `fbset`: Show and set the mode and timings of the current framebuffer +- `fim`: Manually render an image to the framebuffer + +### Device Tree Overlay + +The device tree overlay will need to be built and selected in uBoot (or similar) for your particular target platform. See specific platform docs for more. + +Regardless of the platform-specific configuration, these settings will be correct for the timing in any video mode: + +```dts + hsync-active = <0>; + vsync-active = <0>; + de-active = <1>; + pixelclk-active = <1>; +``` + +## Building the Driver + +Because the driver is made to target an ARM device, it must be cross-compiled. The most reliable way to do this is in an Ubuntu guest machine which will share the project directory. + +To start: + +```sh +$ vagrant up && vagrant rsync && vagrant ssh +$ cd /vagrant/st7701s/ && cargo build --target=armv7-unknown-linux-gnueabihf && scp target/armv7-unknown-linux-gnueabihf/debug/st7701s debian@beaglebone.local:~ +``` + +Remember, you can run `vagrant rsync-auto` in another shell to continually sync changes for "live" development. diff --git a/platforms/beaglebone/README.md b/platforms/beaglebone/README.md new file mode 100644 index 0000000..f0860bb --- /dev/null +++ b/platforms/beaglebone/README.md @@ -0,0 +1,88 @@ +# BeagleBone Black Setup + +The BeagleBone Black was selected as a development board because it uses a variant of the Texas Instruments AM335X, a well-documented and inexpensive platform. + +## First Time Setup + +The best available setup documentation is from the [Beaglebone website](http://beagleboard.org/getting-started). + +If you've used the "IoT" image, or something else that has no Xorg, this will install a minimal X setup: + +**Note: You might not need (or want) Xorg.** + +``` +sudo apt-get install --no-install-recommends -y xserver-xorg-core xserver-xorg-input-all xserver-xorg-video-fbdev +``` + +### Physically Conneting the Display + +### Connecting to Device + +Once the OS is installed, there are three methods which can be used to communicate with the BeagleBone Black: + +- **Ethernet**: + Preferred method. Connect to a host ethernet port and share an internet connection, or to a switch or hub that can easily let you determine the DHCP assigned IP address of the BBB. +- **Serial cable**: + Will let you watch boot. Use the PL2303 cable as [described here](https://elinux.org/Beagleboard:BeagleBone_Black_Serial#Adafruit_4_Pin_Cable_.28PL2303.29). Connect black to pin 1 (has a dot next to it), green to pin 4, white to pin 5. NOTE: It's a six pin header, the last pin is pin 6. Install the [Prolific drivers](http://www.prolific.com.tw/us/showproduct.aspx?p_id=229&pcid=41). Connect to the board before boot with `sudo screen /dev/tty.usbserial 115200 8n1`. +- **USB**: + Not recommended. Strange, fragile setup. Sketchy USB drivers. Follow the [Adafruit guide](https://learn.adafruit.com/ssh-to-beaglebone-black-over-usb/overview) at your own risk. + +Generally, the BeagleBone will pick an IP address like `192.168.x.2`. The non-privileged user is `debian` and the password is `temppwd`. + +## Device Tree Overlay + +The display requires a device tree overlay to be created and loaded in order for the Linux kernel to correctly target the video device. + +### On host machine + +The `.dts` file uses some C headers that must be copied to the BeagleBone in order to compile the overlay: + +```sh +scp -r ./beaglebone/dt-bindings debian@beaglebone.local:~/dts/dt-bindings +``` + +Make changes to `./beaglebone/VE-2IN-BBB.dts`, then copy it over: + +```sh +scp ./beaglebone/VE-2IN-BBB.dts debian@beaglebone.local:~/dts +``` + +### On BeagleBone Black + +Build the `.dts` file and reboot to load it: + +```sh +cd ~/dts && \ +cpp -nostdinc -I . -undef -x assembler-with-cpp VE-2IN-BBB.dts VE-2IN-BBB.dts.preprocessed && \ +dtc -O dtb -o VE-2IN-BBB.dtbo -b 0 -@ VE-2IN-BBB.dts.preprocessed && \ +sudo cp VE-2IN-BBB.dtbo /lib/firmware/VE-2IN-BBB.dtbo && \ +sudo reboot +``` + +In `/boot/uEnv.txt`, comment out the virtual HDMI cape and the universal cape. Then, add this line: + +``` +dtb_overlay=/lib/firmware/VE-2IN-BBB.dtbo +``` + +You may also want to disable the HDMI framer in the kernel command line arguments: + +``` +cmdline=coherent_pool=1M net.ifnames=0 quiet +``` + +## Other things + +These are \*_not necessary_, but documented here for reference. + +### Manually Flash the Reset Pin + +The GPIO `P9_12` on the **board** is `GPIO1_28`/`PIN 60` in software. + +```sh +sudo echo 60 > /sys/class/gpio/export && sleep 1 && \ +sudo echo out > /sys/class/gpio/gpio60/direction && \ +echo 1 > /sys/class/gpio/gpio60/value && \ +echo 0 > /sys/class/gpio/gpio60/value && sleep 0.5 && \ +echo 1 > /sys/class/gpio/gpio60/value +``` diff --git a/platforms/beaglebone/docs/Pinmux.md b/platforms/beaglebone/docs/Pinmux.md new file mode 100644 index 0000000..0107ce3 --- /dev/null +++ b/platforms/beaglebone/docs/Pinmux.md @@ -0,0 +1,61 @@ +### Pin Configuration + +The following pins on the Beaglebone Black's P9 and P8 headers must be connected. See the section on the Linux Device Tree Overlay for details on the pinmux. In most cases, the `SPI0` and `LCD_DATA[15:0]` bus follow the default (`MODE0`) pinmux. The [24-bit configuration](https://elinux.org/24bit_LCD_for_BBB) is slightly different, and requires different muxing of some pins that are normally GPIO. + +![BeagleBone Black Default Pinout](./reference/BeagleBone%20Black%20Pinout%20Diagram.jpeg) + +#### P8 Header + +| Power and Data | | | | +| -------------: | ---: | :--- | :-------- | +| Ground | ₁ ■ | □ ₂ | | +| +3.3v | ₃ ■ | □ ₄ | | +| | ₅ □ | □ ₆ | | +| | ₇ □ | □ ₈ | | +| | ₉ □ | □ ₁₀ | | +| | ₁₁ □ | ■ ₁₂ | Reset | +| | ₁₃ □ | □ ₁₄ | | +| | ₁₅ □ | □ ₁₆ | | +| Chip Select | ₁₇ ■ | ■ ₁₈ | SPI Data | +| | ₁₉ □ | □ ₂₀ | | +| | ₂₁ □ | ■ ₂₂ | SPI Clock | +| | ₂₃ □ | □ ₂₄ | | +| | ₂₅ □ | □ ₂₆ | | +| | ₂₇ □ | □ ₂₈ | | +| | ₂₉ □ | □ ₃₀ | | +| | ₃₁ □ | □ ₃₂ | | +| | ₃₃ □ | □ ₃₄ | | +| | ₃₅ □ | □ ₃₆ | | +| | ₃₇ □ | □ ₃₈ | | +| | ₃₉ □ | □ ₄₀ | | +| | ₄₁ □ | □ ₄₂ | | +| | ₄₃ □ | □ ₄₄ | | +| | ₄₅ □ | □ ₄₆ | | + +#### P9 Header + +| 16-Bit | | | | | 24-Bit | | | | +| -------: | ---: | :--- | :------------- | --- | -------------: | ---: | :--- | :------------- | +| 📕R[ 0 ] | ₁ ■ | ■ ₂ | 📘B[ 0 ] | | | ₁ □ | □ ₂ | | +| | ₃ □ | □ ₄ | | | | ₃ □ | □ ₄ | | +| | ₅ □ | □ ₆ | | | | ₅ □ | □ ₆ | | +| | ₇ □ | □ ₈ | | | | ₇ □ | □ ₈ | | +| | ₉ □ | □ ₁₀ | | | | ₉ □ | □ ₁₀ | | +| | ₁₃ □ | □ ₁₄ | | | Active, unused | ₁₃ ■ | ■ ₁₄ | Active, unused | +| | ₁₁ □ | □ ₁₂ | | | Active, unused | ₁₁ ■ | ■ ₁₂ | Active, unused | +| | ₁₅ □ | □ ₁₆ | | | 📕R[ 0 ] | ₁₅ ■ | ■ ₁₆ | 📘B[ 0 ] | +| | ₁₇ □ | □ ₁₈ | | | Active, unused | ₁₇ ■ | ■ ₁₈ | Active, unused | +| | ₁₉ □ | □ ₂₀ | | | Active, unused | ₁₉ ■ | ■ ₂₀ | Active, unused | +| | ₂₁ □ | □ ₂₂ | | | | ₂₁ □ | □ ₂₂ | | +| | ₂₃ □ | □ ₂₄ | | | | ₂₃ □ | □ ₂₄ | | +| | ₂₅ □ | □ ₂₆ | | | | ₂₅ □ | □ ₂₆ | | +| VSYNC | ₂₇ ■ | ■ ₂₈ | Pixel Clock | | VSYNC | ₂₇ ■ | ■ ₂₈ | Pixel Clock | +| HSYNC | ₂₉ ■ | ■ ₃₀ | Display Enable | | HSYNC | ₂₉ ■ | ■ ₃₀ | Display Enable | +| 📕R[ 4 ] | ₃₁ ■ | ■ ₃₂ | 📕R[ 5 ] | | 📘B[ 4 ] | ₃₁ ■ | ■ ₃₂ | 📘B[ 5 ] | +| 📕R[ 3 ] | ₃₃ ■ | ■ ₃₄ | 📕R[ 1 ] | | 📘B[ 3 ] | ₃₃ ■ | ■ ₃₄ | 📘B[ 1 ] | +| 📕R[ 2 ] | ₃₅ ■ | ■ ₃₆ | 📗G[ 5 ] | | 📘B[ 2 ] | ₃₅ ■ | ■ ₃₆ | 📗G[ 5 ] | +| 📗G[ 3 ] | ₃₇ ■ | ■ ₃₈ | 📗G[ 4 ] | | 📗G[ 3 ] | ₃₇ ■ | ■ ₃₈ | 📗G[ 4 ] | +| 📗G[ 1 ] | ₃₉ ■ | ■ ₄₀ | 📗G[ 2 ] | | 📗G[ 1 ] | ₃₉ ■ | ■ ₄₀ | 📗G[ 2 ] | +| 📘B[ 5 ] | ₄₁ ■ | ■ ₄₂ | 📗G[ 0 ] | | 📕R[ 5 ] | ₄₁ ■ | ■ ₄₂ | 📗G[ 0 ] | +| 📘B[ 3 ] | ₄₃ ■ | ■ ₄₄ | 📘B[ 4 ] | | 📕R[ 3 ] | ₄₃ ■ | ■ ₄₄ | 📕R[ 4 ] | +| 📘B[ 1 ] | ₄₅ ■ | ■ ₄₆ | 📘B[ 2 ] | | 📕R[ 1 ] | ₄₅ ■ | ■ ₄₆ | 📕R[ 2 ] |