NetCube-Systems-Austria/kumquat-readthedocs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add missing interfaces

Browse Source
This commit is contained in:
Lukas Schmid 2024-10-16 13:09:43 +02:00
parent 757814d9f6
commit c7f6a7bac3
4 changed files with 429 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/interfaces/power.md
View File

@ -1,3 +1,47 @@
# Power Supply
To be documented... X1, F1
The power supply for the Kumquat board is provided through a single terminal block. This document explains how to connect the power supply and provides information about the fuse used for protection.
## Connector Pinout Description
| Location | Description |
| -------- | ------------ |
| X1.1 | M (Negative) |
| X1.2 | L+ (Positive)|
![Power Supply Connector Location](placeholder_image_link)
## Prerequisites
Before connecting the power supply, ensure you have the following:
- A 12V or 24V power supply capable of delivering at least 1 Amp of current.
## Hardware Setup
1. **Connect the Power Supply**:
- Connect the positive terminal of the power supply to the `L+` terminal.
- Connect the negative terminal of the power supply to the `M` terminal.
2. **Power On**:
- Once connected, turn on the power supply. The Kumquat board should begin booting immediately.
![Power Supply Setup](placeholder_image_link)
## Fuse (F1)
The Kumquat board is equipped with a preinstalled 3 Amp Slow Blow fuse (F1). This fuse protects the board's wiring from short circuits or overloads.
![Fuse Location](placeholder_image_link)
### Replacement Information
If you need to replace the fuse, ensure the replacement matches the specifications of the original. The replacement part can be ordered from most suppliers.
**Replacement Part Number**:
[Littelfuse 0453003](https://www.littelfuse.de/products/fuses/surface-mount-fuses/nano-2-fuses/453/453003.aspx)
## Note on 13w24b Revision Boards
**Important**: Boards with the 13w24b revision have a known bug in the Digital IO section, which causes them to get hotter than usual when using a 24V power supply. If you are using this revision, consider using a 12V supply to avoid excessive heat.

83
docs/interfaces/spi-nor-flash.md
View File

@ -1,3 +1,82 @@
# SPI NOR-Flash
# SPI-Nor Flash
To be documented...
The Kumquat board includes an 8MB SPI-Nor Flash memory chip, the Winbond W25Q64JVSIQ. This memory is used to store critical components like the bootloader (U-Boot) and its environment variables, along with providing additional storage for user data. The flash memory is managed using `mtdparts` and divided into several partitions.
## Information
The SPI-Nor Flash contains the following partitions:
- **Bootloader (U-Boot)**: A read-only partition for the bootloader.
- **U-Boot Environment (env1 and env2)**: Two redundant partitions for U-Boot configuration.
- **User Partition**: A partition available for storing user data.
The current configuration is as follows:
```
mtdparts=firmware:512k(u-boot)ro,256k(u-boot-env1),256k(u-boot-env2),-(user)
```
This setup assigns 512KB to U-Boot, 256KB each for U-Boot environment 1 and 2, and the remainder to the `user` partition.
## Checking if the SPI-Nor Flash is Detected
To verify the presence of the SPI-Nor Flash, you can list the MTD devices using the following command:
```sh
cat /proc/mtd
```
The expected output should resemble the following:
```sh
mtd0: 00080000 00010000 "u-boot"
mtd1: 00040000 00010000 "u-boot-env1"
mtd2: 00040000 00010000 "u-boot-env2"
mtd3: 00700000 00010000 "user"
```
The `user` partition (`mtd3` in this case) is where user data can be stored.
## Writing to the SPI-Nor Flash
To write data to the `user` partition of the SPI-Nor Flash, you can use standard Linux tools like `dd` for writing raw data to the MTD block device.
Here is an example of how to write a file to the `user` partition:
1. Prepare the file you want to store in the Flash.
2. Use `dd` to copy the file to the `user` partition:
```sh
dd if=mydata.bin of=/dev/mtd3 bs=4096
```
This writes the contents of `mydata.bin` to the `user` partition (`mtd3`), using a block size of 4096 bytes.
### Reading from the SPI-Nor Flash
To read data from the `user` partition, you can use `dd` to copy the contents to a file:
```sh
dd if=/dev/mtd3 of=readback.bin bs=4096
```
This command copies the content of the `user` partition to `readback.bin`. You can then inspect or process this file as needed.
Alternatively, you can display the content directly in the terminal:
```sh
cat /dev/mtd3
```
This command will print the raw contents of the `user` partition to the terminal.
## Summary of the Flash Layout
| MTD Block | Size | Description |
| --------- | ------ | ------------------ |
| mtd0 | 512KB | U-Boot |
| mtd1 | 256KB | U-Boot Environment 1 |
| mtd2 | 256KB | U-Boot Environment 2 |
| mtd3 | ~6MB | User Partition |
The SPI-Nor Flash on the Kumquat board is divided into fixed partitions, with the `user` partition available for data storage. By using standard Linux commands, you can write and read data to and from the SPI-Nor Flash without needing external tools like `flashcp`.

155
docs/interfaces/usb-otg.md
View File

@ -1,3 +1,154 @@
# USB
# USB-OTG Port
To be documented... X11
The Kumquat board features a USB On-The-Go (OTG) port via a USB-C connector that supports USB 2.0 dual-role functionality. This means the port can act either as a USB host or a USB device, depending on the mode selected. The mode switching is handled by the TUSB320 controller, which is managed directly by the Linux kernel.
| Location | Description |
| -------- | ------------------- |
| X11 | USB-C OTG Connector |
![USB-OTG Connector Location](placeholder_image_link)
## Key Features
- **USB-C Connector**: Supports USB 2.0 protocol.
- **Dual Role Support**: Can function as both a USB host (for peripherals) and a USB device.
- **Power Supply**: In host mode, the port can supply 5V at 500mA to connected devices.
- **Mode Switching**: Automatically managed by the Linux kernel via the TUSB320 controller.
## Mode Switching with TUSB320
The TUSB320 controller allows the system to dynamically switch between USB host mode and USB device mode. In host mode, the Kumquat board can connect and power peripherals like keyboards, mice, or flash drives. In device mode, the board can act as a USB peripheral, such as a mass storage device or a serial device.
The Linux kernel automatically handles the negotiation between device and host modes based on the connected device.
## Sysfs Interface
The USB controller on the Kumquat board is the **Allwinner V3s MUSB** controller, which uses the Linux kernel's MUSB driver. You can access and manage USB OTG settings via the sysfs interface.
The typical path for the MUSB controller's sysfs interface will look something like:
```sh
/sys/class/udc/musb-hdrc.1.auto/
```
## Example 1: Using USB-OTG as a USB-Serial Device (Device Mode)
In this example, we will configure the Kumquat board to act as a USB-serial device when connected to a host computer using the OTG port.
### Steps to Configure USB-Serial Device
1. **Connect the Kumquat Board to the Host PC**
Use a USB Type-C cable to connect the USB-OTG port on the Kumquat board to the host PC.
2. **Enable Device Mode**
The Linux kernel should automatically detect the connection and switch the Kumquat board to device mode via the TUSB320 controller.
3. **Load the USB Gadget Module**
Load the **g_serial** module, which creates a USB serial device that can communicate with the host PC over the USB-OTG port.
```sh
modprobe g_serial
```
4. **Verify the USB Serial Device**
After loading the module, the board will create a new serial device that the host PC can detect. You can check the created device by looking at `/dev`:
```sh
ls /dev/ttyGS0
```
The device `/dev/ttyGS0` should appear, representing the USB-serial interface on the Kumquat board.
5. **Connect to the USB-Serial Device from the Host PC**
On the host PC, open a terminal and use a serial communication program such as `screen` or `minicom` to connect to the serial device. For example:
```sh
screen /dev/ttyUSB0 115200
```
This command connects to the USB-serial device at a baud rate of 115200. You should now be able to send and receive data between the Kumquat board and the host PC.
6. **Stop the USB Serial Device**
To stop the USB-serial device and return to the previous configuration, unload the `g_serial` module:
```sh
rmmod g_serial
```
## Example 2: Using USB-OTG as a USB Host (Connecting a USB Stick)
In this example, we will use the Kumquat board as a USB host to connect and access a USB storage device (such as a USB flash drive).
### Steps to Connect a USB Stick
1. **Connect the USB Stick to the USB-OTG Port**
Plug your USB stick into the USB-C OTG port using an appropriate adapter, if necessary.
2. **Verify Device Detection**
Use the `lsusb` command to verify that the USB stick has been detected by the Kumquat board:
```sh
lsusb
```
You should see output similar to the following, listing the USB stick:
```
Bus 001 Device 002: ID 0781:5581 SanDisk Corp.
```
3. **Mount the USB Stick**
First, create a mount point where the USB stick will be mounted:
```sh
mkdir /mnt/usb
```
Then, find the device name of the USB stick by using the `dmesg` or `lsblk` command:
```sh
lsblk
```
You should see a block device like `/dev/sda1`. Mount the USB stick to the mount point:
```sh
mount /dev/sda1 /mnt/usb
```
4. **Access Files on the USB Stick**
You can now access files on the USB stick from the `/mnt/usb` directory:
```sh
ls /mnt/usb
```
5. **Unmount the USB Stick**
After finishing, unmount the USB stick to safely remove it:
```sh
umount /mnt/usb
```
## Power Considerations
When the Kumquat board operates in host mode, it can supply up to **500mA of current at 5V** to the connected device. This power is supplied directly via the USB-C connector, making it suitable for low-power USB devices.
However, ensure that the total current consumption of all connected devices does not exceed 500mA, as the board may become unstable or fail to power high-demand devices.
## Summary
The USB-OTG port on the Kumquat board provides flexible connectivity for both host and device roles, controlled by the TUSB320 IC. In host mode, the board can connect to and power external devices like USB sticks, while in device mode, it can function as a USB peripheral such as a serial interface. Mode switching is automatic, making the port versatile for a variety of embedded use cases.
For more advanced use cases, such as creating custom USB gadgets, consult the [Linux USB Gadget API documentation](https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt).

151
docs/interfaces/wifi-bt.md
View File

@ -1,3 +1,152 @@
# WiFi & Bluetooth
To be documented...
The Kumquat board is equipped with an **ESP32 module** for both WiFi and Bluetooth functionality. The ESP32 uses the **Espressif esp-hosted-ng firmware**, and the necessary kernel modules are pre-installed on the system. This guide provides an overview of how to connect to a WiFi network using the `NetworkManager` service and how to manage Bluetooth connections.
## Key Features
- **WiFi Interface**: The WiFi interface on the Kumquat board is named `espsta0`.
- **Bluetooth Interface**: The Bluetooth interface is named `hci0`.
- **Firmware**: The ESP32 is controlled via the Espressif esp-hosted-ng firmware.
## Using WiFi with `NetworkManager`
The Kumquat board uses the standard `NetworkManager` service to manage WiFi connections. Here’s how to connect to a WiFi network and enable internet access.
### Checking the WiFi Interface
First, check if the `espsta0` interface is up and running:
```sh
nmcli device status
```
This should show `espsta0` listed as a WiFi device. If it’s not listed, you may need to bring the interface up manually:
```sh
ip link set espsta0 up
```
### Scanning for Available Networks
To scan for nearby WiFi networks:
```sh
nmcli device wifi list
```
This command will output a list of available WiFi networks. Note the SSID of the network you wish to connect to.
### Connecting to a WiFi Network
To connect to a WiFi network, use the following command:
```sh
nmcli device wifi connect "<SSID>" password "<password>"
```
Replace `<SSID>` with the name of your network and `<password>` with the network’s password.
Once connected, you can verify the connection with:
```sh
nmcli connection show
```
This will display the active network connections, including the one established via `espsta0`.
### Verifying Internet Access
After successfully connecting, test the internet connection by pinging a reliable external server:
```sh
ping 8.8.8.8
```
You should receive a response if the connection is successful.
## Using Bluetooth (`hci0`)
The Kumquat board supports Bluetooth through the **hci0** interface, managed by the `BlueZ` stack, which is pre-installed. Below are some common Bluetooth operations such as scanning, pairing, and connecting to devices.
### Bringing Up the Bluetooth Interface
Ensure the Bluetooth interface is up by running:
```sh
hciconfig hci0 up
```
### Scanning for Bluetooth Devices
To scan for nearby Bluetooth devices, use the following command:
```sh
hcitool scan
```
This will output a list of discoverable devices, showing their MAC addresses and device names. Note the MAC address of the device you wish to connect to.
### Pairing with a Bluetooth Device
Once you have the device's MAC address, you can initiate pairing using `bluetoothctl`, a command-line utility to manage Bluetooth devices.
1. Start the `bluetoothctl` tool:
```sh
bluetoothctl
```
2. Enter pairing mode:
```sh
agent on
default-agent
```
3. Scan for devices again within `bluetoothctl`:
```sh
scan on
```
4. Pair with the device by specifying its MAC address:
```sh
pair XX:XX:XX:XX:XX:XX
```
Replace `XX:XX:XX:XX:XX:XX` with the actual MAC address of the Bluetooth device.
5. To connect after pairing, use:
```sh
connect XX:XX:XX:XX:XX:XX
```
6. Trust the device for automatic connections in the future:
```sh
trust XX:XX:XX:XX:XX:XX
```
7. Finally, exit `bluetoothctl`:
```sh
exit
```
### Verifying the Bluetooth Connection
You can verify that the Bluetooth device is connected by running:
```sh
hciconfig hci0
```
This will provide information on the current state of the Bluetooth interface, including any active connections.
## Summary
The Kumquat board offers robust WiFi and Bluetooth support through its integrated ESP32 module. Using standard tools like `NetworkManager` and `bluetoothctl`, you can easily connect to WiFi networks and pair with Bluetooth devices. The board’s dual connectivity capabilities make it ideal for embedded IoT projects requiring wireless communication.
For more advanced uses, refer to the [BlueZ Bluetooth stack documentation](https://www.kernel.org/pub/linux/bluetooth/) and the [NetworkManager documentation](https://networkmanager.dev/docs/).