Skip to content

Commit

Permalink
Update ERADME
Browse files Browse the repository at this point in the history 
Signed-off-by: Ruixi Zhou <[email protected]>
  • Loading branch information
@zhouruixi
zhouruixi committed Dec 2, 2024
1 parent 4b81e4d commit d01c089
Showing 1 changed file with 127 additions and 55 deletions.
182 changes: 127 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,136 @@ Main Features

* __Centralize configuration file in fat32 partition.__ Use a single configuration file to configure almost everything you need. The configuration file path is `/config/gs.conf` and linked to `/etc/gs.conf`. The partition mount to /config is fat32 format, configuration file can be accessed and edited directly on Windows PC. See configuration part for detial.
* __Default wfb key file in fat32 partition.__ `/config/gs.key` and linked to `/etc/gs.key`.
* __Button support.__ There are 8 buttons in plan, they are `up, down, left, right, center and quick 1, 2, 3` buttons. Currently only the quick buttons are used, `quick 1` button start / stop video record, `quick 2` button switch USB OTG mode between host and device, `quick 3` button switch WiFi mode between station and hotspot (Only for 3W).
* __Button support.__ There are 8 buttons in plan, they are `up, down, left, right, middle and quick 1, 2, 3` buttons.
* __LED support.__ Currently support `video record LED (Red)` and `power LED (Green)`. The green and red LED turn on after the SBC is powered on. Red LED turn off after the system is startup completed. The red LED will blink when video record is turn on. The green LED will blink when OTG mode is switched to device.
* __Multiple types of network support.__ Support `WiFi`, `Ethernet` and `USB Net`, See Network Configuration for details.
* __Optional video player.__ Support pixelpilot, fpvue, gstreamer as Video player. Gstreamer not support OSD.
* __Multiple USB OTG gadget functions.__ Support `adbd` and `CDC NCM`, `CDC ACM` and `MASS` supported in plan. Use a data cable to connect the computer and the SBC OTG port, adb device and an additional NCM network card will appear on the computer. NCM can auto get ip address with DHCP.
* __Temperature monitoring and active cooling.__ Support monitoring `RK3566` and `RTL8812EU` temperature and automatically adjust PWM fan speed according to temperature.
* __Multiple WiFi card drivers.__ Currently supports `RTL8812AU, RTL8812EU, RTL8812BU, RTL8812CU, RTL8814AU, RTL8731BU`.
* __USB WiFi card hot plug.__ Support multiple USB WiFi cards with Hotplugging.
* __Two wifibroadcast working modes.__ `standalone` mode is the native mode with the best compatibility, but hot-plugging USB WiFi card will briefly interrupted the stream. `aggregator` mode will run wfb_rx aggregator on boot, and run wfb_rx forwarder for each USB WiFi card, hot-plugging USB WiFi card will not interrupt the stram and can receive streams from other external devices through the network like an openwrt router, but may add a little delay (<1ms?)
* __Three wifibroadcast working modes.__ `standalone` mode is the native mode with the best compatibility, but hot-plugging USB WiFi card will briefly interrupted the stream. `aggregator` mode will run wfb_rx aggregator on boot, and run wfb_rx forwarder for each USB WiFi card, hot-plugging USB WiFi card will not interrupt the stram and can receive streams from other external devices through the network like an openwrt router, but may add a little delay (<1ms?). `cluster` mode.
* __Share config and videos with smb.__ Anonymous access with root permissions is enabled by default, which allows you to easily modify configurations, obtain and delete record files. Enter \\192.168.x.x (SBC IP address) in the Windows Explorer address bar to access.
* __Auto extend root partition and rootfs.__ The root partition and rootfs will automatically `expand to the size specified in gs.conf->rootfs_reserved_space` on initial startup.
* __exfat partition for video recordings.__ Automatically create an `exfat partition` using all remaining space during initial startup. The partition will be `mounted to /home/radxa/Videos` for storing video recordings, can get the record files through smb or insert the TF card into the computer.
* __Sequentially increasing video file names.__ SBC has incorrect time without Internet, The gstreamer record video files name sequentially starting from 1000.mkv, Finally video files will be like this: `1000.mkv, 1001.mkv, etc.` PixelPilot record file name use template since this [commit](https://github.com/OpenIPC/PixelPilot_rk/commit/eab6c59e203c22c468a4ce99ff8461ec00d56fc3), Finally video files will be like record_%Y-%m-%d_%H-%M-%S.mp4.
* __send stream over USB tethering and Ethernet__ Video and telemetry stream can send to other device over USB tethering or Ethernet, witch can be played with Android QGroundControl,PixelPilot etc. Notice: share stream using multicast by default, not working with windows QGroundControl.
* __Forward SBC port to IPC over wfb tun__ Forward SBC port 2222/8080 to IPC port 22/80 over wfb tun
* __Forward SBC port to IPC over wfb tun__ Forward SBC port 2222/8080 to IPC port 22/80 over wfb tun.
* __WFB channel scan__
* __Version in /etc/gs-release__
* __Auto build with github action.__


Configuration [ gs.conf for details ]
-------------------------------------

### 1. Button Configuration
There are some built-in functions that can be bound to button behaviors.
* Buttons
+ Q1, Q2, Q3, CU, CD, CL, CR. PIN configured in the GPIO section.
* Button behaviors
+ single press
+ long press(Pressing for more than 2 seconds)
* Button functions
+ change_wifi_mode: change wifi mode between station and hotspot.(Radxa zero 3W)
+ change_otg_mode: change usb otg port between host and device.
+ scan_wfb_channel: search wifi channel used by drone.
* Default button behavior function
+ Q1
- single press: start/stop record.
- long press: cleanup record files in order of file names until remaining space(MB) of record partition is large than `rec_dir_freespace_min` settings.
- second long press: delete all record files(in 60 seconds after first long press).
- __CAUTION:__ Quick button 1 is used for record and cannot be customized.
+ Q2
- single press: scan_wfb_channel
- long press: change_otg_mode
+ Q3
- single press: null
- long press: change_wifi_mode

### 2. GPIO Configuration
Default buttons and LEDs PIN number.
* Quick button PIN
+ BTN_Q1_PIN='32'
+ BTN_Q2_PIN='38'
+ BTN_Q3_PIN='40'
* Custom button PIN
+ BTN_CU_PIN='18'
+ BTN_CD_PIN='16'
+ BTN_CL_PIN='13'
+ BTN_CR_PIN='11'
* LED PIN
+ RED_LED_PIN='22'
+ GREEN_LED_PIN='15'
+ BLUE_LED_PIN='12'

### 3. Network Configuration
* __WiFi:__ `wlan0`
+ `station mode:` Default connect to an open WiFi named `OpenIPC` if not configured.
+ `hotspot mode:` Default SSID is `SBC-GS` with password `12345678`, IP is `192.168.4.1/24`
* __Bridge:__ `br0` Default `DHCP client` with static IP `192.168.1.20/24, 10.0.36.254/24`
* __Ethernet:__ `eth0` Default slave of br0.
* __USB tethering:__ `usb0` Default slave of br0.
* __USB gadget ncm:__ `radxa0` Default `DHCP server` with static IP `192.168.2.20/24`

### 4. Video Configuration
* `video_on_boot`: used to control showing video or terminal console after startup. Default is `yes`. Set it to `no` will boot into the terminal and only recommended for development and debugging.
* `osd_config_file`: pixelpilot's osd config file. Default is `/config/pixelpilot_osd.json`. Use `/config/pixelpilot_osd_simple.json` for less osd elements when using msposd.
* `screen_mode`: used to set the screen resolution and refresh rate. e.g. `1920x1080@60`. Default is blank and will auto detect by pixelpilot or SBC. Recommended set it manually only when preferred screen mode is not the best.
* __CAUTION:__ Resolution is limited to 1920x1080 by radxa, can changed by setting `max_resolution_4k` to `yes` in `System Configuration` section.

### 5. Record Configuration
* `REC_Dir`: the record storage location. Default is `/home/radxa/Videos`.
* `rec_dir_freespace_min`: the minimum remaining space before recording. When press the record button, if remaining space is lower than this value, it will prompt that there is insufficient space and the recording will not start. Default is `1000`MB.
* `REC_FPS`: Record video fps and must same video fps set on drone. Default is `60`.
* __CAUTION:__ OSD will not be recorded.

### 6. Wifibroadcast Configuration

### 7. System Configuration
#### Recommended GPIO Functions
| Purpose#1 | Recommended Function#1 | Pin#1 | Pin#2 | Recommended Function#2 | Purpose#2 |
| ---------------: | -------------------------: | ----: | ----- | ------------------------- | ---------------- |
| +3.3V | +3.3V | 1 | 2 | +5.0V | +5.0V |
| telemetry | UART3_RX_M0 | 3 | 4 | +5.0V | +5.0V |
| telemetry | UART3_TX_M0 | 5 | 6 | GND | GND |
| PWM_FAN | PWM14_M0 | 7 | 8 | UART2_TX_M0 | DEBUG |
| GND | GND | 9 | 10 | UART2_RX_M0 | DEBUG |
| BTN_R | GPIO3_A1 | 11 | 12 | GPIO3_A3 | BTN_L |
| BTN_U | GPIO3_A2 | 13 | 14 | GND | GND |
| BTN_D | GPIO3_B0 | 15 | 16 | PWM8_M0 / UART4_RX_M1 | AAT_SERVO |
| +3.3V | +3.3V | 17 | 18 | PWM9_M0 / UART4_TX_M1 | AAT_SERVO |
| SPI_SCREEN | SPI3_MOSI_M1 / PWM15_IR_M1 | 19 | 20 | GND | GND |
| SPI_SCREEN | SPI3_MISO_M1 / UART9_TX_M1 | 21 | 22 | GPIO3_C1 | SPI_SCREEN |
| SPI_SCREEN | SPI3_CLK_M1 / PWM14_M1 | 23 | 24 | SPI3_CS0_M1 / UART9_RX_M1 | SPI_SCREEN |
| GND | GND | 25 | 26 | NC | NC |
| COMPASS / USB D+ | I2C4_SDA_M0 / USB D+ | 27 | 28 | I2C4_SCL_M0 / USB D- | COMPASS / USB D- |
| SPI_SCREEN | GPIO3_B3 | 29 | 30 | GND | GND |
| BTN_Q1 | GPIO3_B4 | 31 | 32 | UART5_TX_M1 | GPS |
| GPS | UART5_RX_M1 | 33 | 34 | GND | GND |
| BTN_Q2 | GPIO3_A4 | 35 | 36 | GPIO3_A7 | RECORD_RED_LED |
| BTN_Q3 | GPIO1_A4 | 37 | 38 | GPIO3_A6 | PWR_GREEN_LED |
| GND | GND | 39 | 40 | GPIO3_A5 | RC_BLUE_LED |

### 8. Cooling Configuration


Files and Services
------------------

* __build files:__ script files for build images
* __workflows files:__ Auto build images using github action
* __gs files:__
1. Configuration file `/config/gs.conf`
2. wfb key file `/config/gs.key`
3. script files `/home/radxa/gs/[button.sh, channel-scan.sh, fan.sh, gs-init.sh, gs.sh, stream.sh, wfb.sh]`
4. udev rule files `/etc/udev/rules.d/[98-gadget.rules, 99-wfb.rules]`
1. Configuration file `/config/gs.conf`
2. wfb key file `/config/gs.key`
3. script files `/home/radxa/gs/[button.sh, channel-scan.sh, fan.sh, gs-init.sh, gs.sh, stream.sh, wfb.sh]`
4. udev rule files `/etc/udev/rules.d/[98-gadget.rules, 99-wfb.rules]`
* __Services:__
1. `gs`.service
2. `stream`.service (temporary unit)
3. `button`.service (temporary unit)
4. `fan`.service (temporary unit)
5. unnamed temporary services started for each USB WiFi card in wfb aggregator mode
1. `gs`.service
2. `stream`.service (temporary unit)
3. `button`.service (temporary unit)
4. `fan`.service (temporary unit)
5. unnamed temporary services started for each USB WiFi card in wfb aggregator mode
```bash
GS Directory Tree
/
Expand Down Expand Up @@ -105,58 +201,35 @@ GS Directory Tree

Hardware
--------

__Designed for and tested on Radxa Zero 3W/3E only.__
* __Buttons:__ All buttons must connect to 3.3V.
* __LEDs:__
1. GPIO work in `Push-Pull` mode. `GPIO->Resistor->LED->GND`
2. GPIO work in `Open-Drain` mode.
```
3V3->Resistor--->LED->GND
│  
GPIO
```


DEBUG
-----
1. GPIO work in `Push-Pull` mode. `GPIO->Resistor->LED->GND`
2. GPIO work in `Open-Drain` mode.
```
3V3->Resistor--->LED->GND
│  
GPIO
```
1. ssh over hotspot, ethernet or usb net. Default username/password is radxa/radxa and root/root
2. [serial console](https://docs.radxa.com/en/zero/zero3/low-level-dev/serial)
3. keyboard
4. adb
Troubleshooting
---------------
Configuration [ gs.conf for details ]
-------------------------------------

### 1. Button Configuration

### 2. LED Configuration

### 3. Network Configuration
1. __WiFi:__ `wlan0`
* `station mode:` Default connect to an open WiFi named `OpenIPC` if not configured.
* `hotspot mode:` Default SSID is `SBC-GS` with password `12345678`, IP is `192.168.4.1/24`
2. __Ethernet:__ `eth0` Default slave of br0.
3. __USB Net:__ `radxa0` Default `DHCP server` with static IP `192.168.2.20/24`
4. __USB tethering:__ `usb0` Default slave of br0.
5. __Bridge:__ `br0` Default `DHCP client` with static IP `192.168.1.20/24, 10.0.36.254/24`

### 4. Video Configuration

### 5. Record Configuration

### 6. System Configuration

### 7. Cooling Configuration

### 8. Wifibroadcast Configuration

### 9. GPIO Configuration
1. Access to SBC console. Default username/password is radxa/radxa and root/root
* ssh over network with wireless(hotspot/station), ethernet or usb gadget ncm.
* [serial console](https://docs.radxa.com/en/zero/zero3/low-level-dev/serial) with usb uart.
* terminal console with keyboard.
* adb with usb otg.
2. Check gs service logs
* `systemctl status gs`
* `journalctl -u gs`
TODO
----
* Automatically select the video storage location according to the priority of external storage > TF card > emmc
* [Adaptive-Link](https://github.com/sickgreg/OpenIPC-Adaptive-Link) support
* [improver](https://github.com/OpenIPC/improver) support
Expand All @@ -169,5 +242,4 @@ TODO
Known issues
------------
1. When WiFi is set to station mode, it will enter hotspot mode when it is turned on for the first time after initialization. [ maybe not bad :) ]

0 comments on commit d01c089

Please sign in to comment.