diff --git a/docs/_assets/user.css b/docs/_assets/user.css
index a0f674d7..8b138715 100644
--- a/docs/_assets/user.css
+++ b/docs/_assets/user.css
@@ -144,3 +144,7 @@ ol li::marker {
.md-typeset li .admonition:only-child {
margin: 0;
}
+
+.md-button--stretch {
+ width: 100%;
+}
diff --git a/docs/_config.md b/docs/_config.md
new file mode 100644
index 00000000..6bf55330
--- /dev/null
+++ b/docs/_config.md
@@ -0,0 +1,47 @@
+---
+search:
+ exclude: true
+---
+
+
+??? note "Configuring PiKVM OS"
+
+ Most of the PiKVM configuration files are located in the `/etc/kvmd` directory.
+
+ The `/etc/kvmd/main.yaml` file defines the platform config and **you should never edit it**. To redefine system parameters use the file `/etc/kvmd/override.yaml`. All other files that are also not recommended for editing have read-only permissions.
+
+ In the `/etc/kvmd/meta.yaml` file you can specify some information regarding the host that this PiKVM manages.
+
+ !!! tip
+ A complete list of all parameters can be viewed using the `kvmd -m` command.
+
+ Files with the suffix `*.yaml` uses the [YAML syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html)
+ and describes a parameter tree with key-value pairs of different types.
+ To define the parameters within one section, an indent of 4 spaces is used.
+ Comments starts with the `#` symbol.
+
+ !!! warning "Only 4 spaces should be used for indentation"
+ Be careful when editing YAML and follow this rule.
+ Invalid indentation or tabs instead of spaces will cause an error when starting the services.
+
+ Sections under the same keys **should be merged**:
+
+ * **Wrong:**
+
+ ```yaml
+ kvmd:
+ gpio:
+ drivers: ...
+ kvmd:
+ gpio:
+ scheme: ...
+ ```
+
+ * **Correct:**
+
+ ```yaml
+ kvmd:
+ gpio:
+ drivers: ...
+ scheme: ...
+ ```
diff --git a/docs/_diy_first_launch.md b/docs/_diy_first_launch.md
deleted file mode 100644
index 104e86e4..00000000
--- a/docs/_diy_first_launch.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-search:
- exclude: true
----
-
-
-1. Double-check the correct assembly of the device, and make sure that you have connected
- all the necessary cables to the host: USB, HDMI and ATX.
-
-2. [Flash the memory card with PiKVM OS](https://docs.pikvm.org/flashing_os){target=_blank}
- and insert it to Raspberry Pi.
-
-3. **Carefully read and follow [the First Steps Guide](first_steps.md){target=_blank}.**
- It describes how to perform the first power-on, how to find PiKVM on the network, login, change passwords, and so on.
- **Follow the steps described there and come back to this page.**
-
-4. **Just reminding again:**
-
- {!_passwd.md!}
-
-5. Try to manage the computer using PiKVM with the Web Interface.
- Make sure that you get an image and both keyboard and mouse are working.
- If something doesn't work, check out our [FAQ](faq.md) (it's really useful).
- If nothing helped, you can get support in our [Discord chat](https://discord.gg/bpmXfz5).
-
-6. ??? note "Note for the HDMI-USB dongle"
-
- Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected.
- This may lead to the fact that if you boot the server without an active stream, the server will not detect
- your capture card. This is easy to fix:
-
- * Switch filesystem to RW-mode:
- ```console
- [root@pikvm ~]# rw
- ```
-
- * Edit file `/etc/kvmd/override.yaml` and add these lines:
- ```yaml
- kvmd:
- streamer:
- forever: true
- cmd_append: [--slowdown]
- ```
-
- * Finish:
- ```console
- [root@pikvm ~]# ro
- [root@pikvm ~]# systemctl restart kvmd
- ```
-
- * Check that everything is working.
-
-7. Configure access to PiKVM from the Internet using [port forwarding](https://docs.pikvm.org/port_forwarding)
- or [Tailscale VPN](https://docs.pikvm.org/tailscale), if you need it.
-
-8. Explore the features of PiKVM using the site's table of contents and have fun!
diff --git a/docs/_passwd.md b/docs/_passwd.md
index d6c37504..b0b5c2bc 100644
--- a/docs/_passwd.md
+++ b/docs/_passwd.md
@@ -4,7 +4,7 @@ search:
---
-??? danger "✮ ✮ ✮ CHANGE THE PASSWORDS! ✮ ✮ ✮"
+??? note "Changing PiKVM Passwords"
PiKVM comes with the following default passwords:
* **Linux OS-level admin** (SSH, console...):
diff --git a/docs/_update_os.md b/docs/_update_os.md
index d74eb234..59b11658 100644
--- a/docs/_update_os.md
+++ b/docs/_update_os.md
@@ -4,7 +4,7 @@ search:
---
-??? example "Updating PiKVM OS"
+??? note "Updating PiKVM OS"
To update, run following commands under the `root` user:
diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md
new file mode 100644
index 00000000..800f45a5
--- /dev/null
+++ b/docs/cheatsheet.md
@@ -0,0 +1,61 @@
+---
+title: PiKVM Cheat Sheet
+description: "Getting started with PiKVM"
+---
+
+# PiKVM Cheat Sheet
+
+Here are **first steps guides** for each PiKVM device:
+
+
+
+[PiKVM V4 Mini & Plus](v4.md){ .md-button .md-button--stretch }
+
+[PiKVM V3](v3.md){ .md-button .md-button--stretch }
+
+[DIY PiKVM V2](v2.md){ .md-button .md-button--stretch }
+
+[DIY PiKVM V1](v1.md){ .md-button .md-button--stretch }
+
+
+
+
+-----
+## Quick Tips
+
+{!_passwd.md!}
+
+{!_config.md!}
+
+{!_update_os.md!}
+
+??? note "Connect to PiKVM via SSH"
+
+ SSH is the most common remote access method in the Linux world. PiKVM is accessible via SSH. This method is used to manage the device:
+
+ * **Linux, MacOS:** Open any terminal application and run: `ssh root@192.168.0.100` or `ssh root@pikvm`.
+ * **Windows:** Use [PuTTY](https://www.putty.org/) for this.
+
+ **The default `root` password is `root`.**
+
+??? note "Connect to PiKVM via serial console"
+
+ A serial console is a convenient and fast way to connect to PiKVM when there is no network, or get boot logs and a console if something goes wrong.
+
+ 1. Connect to the physical UART console:
+
+ * On PiKVM V3 or V4, you have a built-in USB-UART adapter in your device. Just disconnect the OTG cable and place the USB-C end into `IOIOI` port on V4 (or `CON` port on V3). Place the USB-A end into the port you want serial to be accessed, typically done on the host. If you have a Windows host, you may need to install this [driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers), other OS's may not need one.
+
+ * On DIY PiKVM V1 or V2, you'll need to get the right TTY to USB cable, we recommend the [RPi Debug Probe](https://www.pishop.us/product/raspberry-pi-debug-probe/) and follow existing RPi TTY serial setups.
+
+ 2. Install GNU Screen on Linux or macOS host, or [Putty](https://www.putty.org/) on Windows.
+
+ 3. Select the COM port in Putty (you can verify this looking in Device Manager), then select **115200** baud, or use `screen /dev/ttyUSB0 115200` for other OS's
+
+ 4. You should now be able to see and interact with the Serial Port.
+
+
+-----
+## Getting User Support
+
+If something doesn't work, check out our [FAQ](faq.md). Otherwise, head straight to our [Discord chat](https://discord.gg/bpmXfz5).
diff --git a/docs/config.md b/docs/config.md
deleted file mode 100644
index 4c59402e..00000000
--- a/docs/config.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Structure of configuration files
-description: "How PiKVM configuration files are structured"
----
-
-# Structure of configuration files
-
-Most of the PiKVM configuration files are located in the `/etc/kvmd` directory.
-
-The `/etc/kvmd/main.yaml` file defines the platform config and **you should never edit it**. To redefine system parameters use the file `/etc/kvmd/override.yaml`. All other files that are also not recommended for editing have read-only permissions.
-
-In the `/etc/kvmd/meta.yaml` file you can specify some information regarding the host that this PiKVM manages.
-
-!!! tip
- A complete list of all parameters can be viewed using the `kvmd -m` command.
-
-Files with the suffix `*.yaml` uses the [YAML syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html)
-and describes a parameter tree with key-value pairs of different types.
-To define the parameters within one section, an indent of 4 spaces is used.
-Comments starts with the `#` symbol.
-
-!!! warning "Only 4 spaces should be used for indentation"
- Be careful when editing YAML and follow this rule.
- Invalid indentation or tabs instead of spaces will cause an error when starting the services.
-
-??? example "Sections under the same keys should be merged"
- * **Wrong:**
-
- ```yaml
- kvmd:
- gpio:
- drivers: ...
- kvmd:
- gpio:
- scheme: ...
- ```
-
- * **Correct:**
-
- ```yaml
- kvmd:
- gpio:
- drivers: ...
- scheme: ...
- ```
\ No newline at end of file
diff --git a/docs/first_steps.md b/docs/first_steps.md
deleted file mode 100644
index 23764543..00000000
--- a/docs/first_steps.md
+++ /dev/null
@@ -1,209 +0,0 @@
----
-title: First steps with PiKVM
-description: "Getting started with PiKVM: power on and access the remote host"
----
-
-# First steps
-
-This guide is written primarily with V3 and V4 Mini/Plus in mind and covers the basic steps: what ports to connect and how to access a remote host that your PiKVM is connected to.
-
------
-
-## Wiring
-
-Let's connect all the wires before you power up the device.
-
-1. Connect **Ethernet** to the network (**not applicable** to DIY PiKVM built with Pi Zero 2).
-
-2. Connect the **HDMI input** and the **OTG** port (USB emulation) to the remote computer.
-
-3. Optionally, connect the **[ATX port](atx_board.md)** to control the power of the remote host.
-
-## Power up
-
-1. Optional: [setting up Wi-Fi or static IP](on_boot_config.md) before booting.
- *Remember that there is nothing more reliable than wired Ethernet.*
-
-2. **Power up the device.**
-
-3. **Do not turn off the device until it's fully booted for the first time.**
- *After turning on the power, PiKVM OS will generate unique SSH keys and certificates
- and perform all necessary operations on the memory card. It takes a few minutes.*
-
-## Connect and set up
-
-### Configure the display
-
-The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
-
-To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
-
-### Access PiKVM
-
-By default, PiKVM receives a dynamic IP address via DHCP. PiKVM V3 and V4 will show it in the top row of the OLED display:
-
-```console
-192.168.0.100
-(|) iface: eth0
-cpu: 1% mem: 13%
-```
-
-??? example "PiKVM without OLED: finding device in the network"
-
- To determine the IP address of your PiKVM, use one of the following methods:
-
- * **Common way:** Open the web interface of your router and find the list of issued IP addresses there.
- * **Linux-only:** Use command `arp-scan --localnet`.
- * **Linux, MacOS, Windows:** Download and run [Angry IP Scanner](https://angryip.org).
- * **Windows PowerShell:** Use command `arp -a`.
-
- In order to find PiKVM using the ARP commands, you need to look for the following MACs: `B8:27:EB`, `DC:A6:32` or `E4:5F:01`.
-
-Let's assume that PiKVM has received the address `192.168.0.100` and has also been assigned a hostname `pikvm`.
-
-Type the URL in the browser's address bar and press **Enter**: https://192.168.0.26/ or https://pikvm/.
-
-
-
-Submit the default credentials and click **Login**:
-
-- Username: `admin`
-- Password: `admin`
-- 2FA Code: disabled by default, skip this field
-
-You will see the initial dashboard screen of the PiKVM where you can access the remote desktop, connect to the PiKVM command line, or log out:
-
-
-
-### Change the default passwords
-
-For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time. To do that:
-
-1. On the initial dashboard screen, click the **Terminal** button to open the web terminal. You will see this command line interface:
-
- 
-
-2. Gain superuser privileges:
-
- ```console
- $ su -
- ```
-
- When prompted for password, use `root`.
-
-3. Run `rw` to change the access to the SD card to the write mode:
-
- ```console
- [root@pikvm ~]# rw
- ```
-
-4. Change the password for the superuser:
-
- ```console
- [root@pikvm ~]# passwd root
- ```
-
- Submit the new password, retype it the second time to confirm, press **Enter**, and you should see this:
-
- ```console
- passwd: password updated successfully
- ```
-
-5. Change the password for web access:
-
- ```console
- [root@pikvm ~]# kvmd-htpasswd set admin
- ```
-
- Submit the new password, retype it the second time to confirm, and press **Enter**.
-
-6. Run `ro` to change the access to the SD card back to the read-only mode:
-
- ```console
- [root@pikvm ~]# ro
- ```
-
-7. Press **Ctrl+D** or type "exit" and press **Enter** to drop the root privileges.
-
-8. Go back one page in the browser. You should be back to the initial dashboard screen.
-
-### Access the remote system
-
-1. On the initial dashboard screen, click the **KVM** button to access the remote desktop.
-
-2. You should now see the host system's display and interact with it remotely using a keyboard and a mouse.
-
- 
-
-There are two alternative ways to connect to the PiKVM:
-
-??? example "Connect to PiKVM via SSH"
-
- SSH is the most common remote access method in the Linux world. PiKVM is accessible via SSH. This method is used to manage the device:
-
- * **Linux, MacOS:** Open any terminal application and run: `ssh root@192.168.0.100` or `ssh root@pikvm`.
- * **Windows:** Use [PuTTY](https://www.putty.org/) for this.
-
- **The default `root` password is `root`.**
-
-??? example "Connect to PiKVM via serial console"
-
- A serial console is a convenient and fast way to connect to PiKVM when there is no network, or get boot logs and a console if something goes wrong.
-
- 1. Connect to the physical UART console:
-
- * On PiKVM V3 or V4, you have a built-in USB-UART adapter in your device. Just disconnect the OTG cable and place the USB-C end into `IOIOI` port on V4 (or `CON` port on V3). Place the USB-A end into the port you want serial to be accessed, typically done on the host. If you have a Windows host, you may need to install this [driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers), other OS's may not need one.
-
- * On DIY PiKVM V1 or V2, you'll need to get the right TTY to USB cable, we recommend the [RPi Debug Probe](https://www.pishop.us/product/raspberry-pi-debug-probe/) and follow existing RPi TTY serial setups.
-
- 2. Install GNU Screen on Linux or macOS host, or [Putty](https://www.putty.org/) on Windows.
-
- 3. Select the COM port in Putty (you can verify this looking in Device Manager), then select 115200, or use `screen /dev/ttyUSB0 115200` for other OS's
-
- 4. You should now be able to see and interact with the Serial Port.
-
-## Further steps
-
-1. **Get to know PiKVM OS**: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
-
-2. **Update and customize the system**:
-
- - [Update](_update_os.md) the PiKVM operating system.
- - [Harden the remote access](auth.md) by enabling 2FA and setting session expiration time.
- - Configure access to PiKVM from the Internet using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md).
- - Enable a microphone for [two-way audio](audio.md) (**only for PiKVM V3 and V4 Mini/Plus**).
- - Enable [HDMI pass-through](pass.md) (**only for PiKVM V4 Plus**)..
-
-3. **Configure hardware**:
-
- - Set up [ATX connection](atx_board.md).
- - Install and set up [Wi-Fi antenna](wifi.md).
- - Install and set up [LTE/5G modem](modem.md) (**only for PiKVM V4 Plus**).
- - Choose Fahrenheit over Celsius to display on the OLED:
-
-??? note "How to set up Fahrenheit"
-
- Create a directory for a configuration file:
-
- ```console
- [root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d
- ```
-
- Create file `/etc/systemd/system/kvmd-oled.service.d/override.conf`:
-
- ```ini
- [Service]
- ExecStart=
- ExecStart=/usr/bin/kvmd-oled --clear-on-exit --fahrenheit
- ```
-
- Then run `systemctl restart kvmd-oled`. In some cases, if you still do not see Fahrenheit being displayed, reboot the device.
-
-## Basic troubleshooting
-
-{!_basic_troubleshooting.md!}
-
-
-## Getting user support
-
-If something doesn't work, check out our [FAQ](faq.md). Otherwise, head straight to our [Discord chat](https://discord.gg/bpmXfz5).
diff --git a/docs/v1.md b/docs/v1.md
index a891e244..9d57dd15 100644
--- a/docs/v1.md
+++ b/docs/v1.md
@@ -120,7 +120,7 @@ description: Getting started with PiKVM V1
## Wiring
!!! warning
- Double check that the circuit is assembled correctly to avoid any damage of the hardware.
+ Double check that the circuit is assembled correctly to avoid any damage of the hardware.
PiKVM V1 requires several items available separately:
@@ -151,6 +151,14 @@ After turning on the power, PiKVM OS generates unique SSH keys and certificates
**Do not turn off the device until it's fully booted for the first time.**
+-----
+## Configure the display
+
+The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
+
+To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
+
+
-----
## Access PiKVM
@@ -252,7 +260,32 @@ To do that:
- Get to know PiKVM OS: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
-- Set up [ATX connection](atx_board.md) if you need to control the power of the remote system.
+- ??? note "Note for the HDMI-USB dongle"
+
+ Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected.
+ This may lead to the fact that if you boot the server without an active stream, the server will not detect
+ your capture card. This is easy to fix:
+
+ * Switch filesystem to RW-mode:
+ ```console
+ [root@pikvm ~]# rw
+ ```
+
+ * Edit file `/etc/kvmd/override.yaml` and add these lines:
+ ```yaml
+ kvmd:
+ streamer:
+ forever: true
+ cmd_append: [--slowdown]
+ ```
+
+ * Finish:
+ ```console
+ [root@pikvm ~]# ro
+ [root@pikvm ~]# systemctl restart kvmd
+ ```
+
+ * Check that everything is working.
-----
diff --git a/docs/v2.md b/docs/v2.md
index 5515987b..274c9a5a 100644
--- a/docs/v2.md
+++ b/docs/v2.md
@@ -182,6 +182,14 @@ After turning on the power, PiKVM OS generates unique SSH keys and certificates
**Do not turn off the device until it's fully booted for the first time.**
+-----
+## Configure the display
+
+The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
+
+To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
+
+
-----
## Access PiKVM
@@ -283,7 +291,32 @@ To do that:
- Get to know PiKVM OS: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
-- Set up [ATX connection](atx_board.md) if you need to control the power of the remote system.
+- ??? note "Note for the HDMI-USB dongle"
+
+ Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected.
+ This may lead to the fact that if you boot the server without an active stream, the server will not detect
+ your capture card. This is easy to fix:
+
+ * Switch filesystem to RW-mode:
+ ```console
+ [root@pikvm ~]# rw
+ ```
+
+ * Edit file `/etc/kvmd/override.yaml` and add these lines:
+ ```yaml
+ kvmd:
+ streamer:
+ forever: true
+ cmd_append: [--slowdown]
+ ```
+
+ * Finish:
+ ```console
+ [root@pikvm ~]# ro
+ [root@pikvm ~]# systemctl restart kvmd
+ ```
+
+ * Check that everything is working.
-----
diff --git a/mkdocs.yml b/mkdocs.yml
index db063bdb..dffe23f3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -71,6 +71,8 @@ plugins:
"4g.md": "modem.md"
"usb_dynamic.md": "usb.md"
"webrtc.md": "video.md"
+ "first_steps.md": "cheatsheet.md"
+ "cheat_sheet.md": "cheatsheet.md"
- glightbox:
touchNavigation: false
loop: false
@@ -94,7 +96,6 @@ nav:
- "Getting started":
- "First steps": first_steps.md
- "Web UI Overview": webui.md
- - "Configure PiKVM OS": config.md
- "Authentication & 2FA": auth.md
- "FAQ & Troubleshooting": faq.md
- "Flashing OS": flashing_os.md