Add documentation
This commit is contained in:
Corey Vixie
parent
4ae992c985
commit
384dd78057
57
README.md
Normal file
57
README.md
Normal file
@ -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.
|
||||
88
platforms/beaglebone/README.md
Normal file
88
platforms/beaglebone/README.md
Normal file
@ -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
|
||||
```
|
||||
61
platforms/beaglebone/docs/Pinmux.md
Normal file
61
platforms/beaglebone/docs/Pinmux.md
Normal file
@ -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.
|
||||
|
||||
|
||||
|
||||
#### 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 ] |
|
||||
Loading…
x
Reference in New Issue
Block a user