docs: update and expand troubleshooting sections

This commit is contained in:
alfrix 2023-05-27 13:11:19 -06:00
parent 85ba01f2d8
commit eb24987b27
14 changed files with 359 additions and 153 deletions

View File

@ -26,7 +26,6 @@ In general, if the device can show a GNU/Linux desktop, then KlipperScreen shoul
Follow the manufacturer instructions on how to install your screen. In general if you see a white screen, then it's not properly installed, ensure that you at least see a console, Then [install](Installation.md) KlipperScreen, if you are having troubles refer to the [troubleshooting page](Troubleshooting.md) for further information.
## Screen rotation
Currently there is no support for rotation at runtime, do not use xrandr to rotate the screen.
Configure the server to start in the desired orientation, there are many ways to achieve this, here is one:
@ -56,6 +55,7 @@ Save the file and restart KlipperScreen.
sudo service KlipperScreen restart
```
TODO: LCDSHOW way
## Touchscreen touch rotation
If your touchscreen isn't registering touches properly after the screen has been rotated, you will need to apply a

View File

@ -3,17 +3,17 @@
### Main Menu
![Main Menu](img/panels/main_panel.png)
### [Job Status](Job_status.md)
### [Job Status](Panels/Job_status.md)
```py
panel: job_status
```
![Job Status](img/panels/job_status.png)
[![Job Status](img/panels/job_status.png)](Panels/Job_status.md)
### [Bed Level](Screws.md)
### [Bed Level](Panels/Screws.md)
```py
panel: bed_level
```
![Bed Level](img/panels/bed_level.png)
[![Bed Level](img/panels/bed_level.png)](Panels/Screws.md)
### Bed Mesh
```py
@ -108,14 +108,14 @@ panel: system
```
![System Panel](img/panels/system.png)
### [Temperature](Temperature.md)
### [Temperature](Panels/Temperature.md)
```py
panel: temperature
```
![Temperature](img/panels/temperature.png)
[![Temperature](img/panels/temperature.png)](Panels/Temperature.md)
### [Z Calibrate](Zcalibrate.md)
### [Z Calibrate](Panels/Zcalibrate.md)
```py
panel: zcalibrate
```
![Z Calibrate](img/panels/zcalibrate.png)
[![Z Calibrate](img/panels/zcalibrate.png)](Panels/Zcalibrate.md)

View File

@ -2,7 +2,7 @@
Also known as "Print Status" or the "printing panel" shows the relevant information of the current print.
![Screenshot](img/panels/job_status.png)
![Screenshot](../img/panels/job_status.png)
!!! tip
the third row shows the LCD message (`M117`)
@ -10,19 +10,19 @@ Also known as "Print Status" or the "printing panel" shows the relevant informat
This panel has more information than it shows by default, just click/tap the corresponding the status buttons to access the extra information
## Position info
![speed_screenshot](img/panels/job_status_speed.png)
![speed_screenshot](../img/panels/job_status_speed.png)
!!! note
Layer is calculated from object height, it may not be accurate if variable layer is used
If that is the case use the Layer Progress method described in the [Quicktips](Quicktips.md#layer-progress)
## Extrusion info
![extrusion_screenshot](img/panels/job_status_extrusion.png)
![extrusion_screenshot](../img/panels/job_status_extrusion.png)
## Time info
![time_screenshot](img/panels/job_status_time.png)
![time_screenshot](../img/panels/job_status_time.png)
## Extra temperature items
By default only extruder and bed temperatures will be available but additional items can be defined
using ["titlebar_items" in the config](Configuration.md#printer-options)
using ["titlebar_items" in the config](../Configuration.md#printer-options)

View File

@ -1,6 +1,6 @@
# Bed level
![Bed Level](img/panels/bed_level.png)
![Bed Level](../img/panels/bed_level.png)
For this panel to appear in the menu `[bed_screws]` or `[screws_tilt_adjust]` need to be defined in Klipper config (printer.cfg)

View File

@ -6,18 +6,18 @@ this includes extruders, heaters, sensors and temperature_fans.
There are 3 main modes of operation:
## Preheat
[Define profiles](Configuration.md#preheat-options) to quickly change the target temperature of multiple selected devices.
[Define profiles](../Configuration.md#preheat-options) to quickly change the target temperature of multiple selected devices.
This is the default mode when not printing.
![Preheat_screenshot](img/panels/temperature.png)
![Preheat_screenshot](../img/panels/temperature.png)
## Delta adjust
Change the target of the selected devices, the amount is selectable.
This is the default mode while printing
![Delta_screenshot](img/panels/temperature_delta.png)
![Delta_screenshot](../img/panels/temperature_delta.png)
## Direct input with keypad
Allows to set the exact temperature using the keypad.
![Keypad_screenshot](img/panels/temperature_keypad.png)
![Keypad_screenshot](../img/panels/temperature_keypad.png)

View File

@ -2,7 +2,7 @@
This panel supports various modes of operation to assist in the calibration of the Z axis of the machine.
It's strongly suggested to read Klipper documentation about [Bed level](https://www.klipper3d.org/Bed_Level.html)
![Screenshot](img/panels/zcalibrate.png)
![Screenshot](../img/panels/zcalibrate.png)
## Buttons

View File

@ -1,6 +1,4 @@
This page will have common problems and common solutions to those problems.
# First Steps
The first step to troubleshooting any problem is getting the cause of the error.
@ -10,14 +8,14 @@ The first step to troubleshooting any problem is getting the cause of the error.
!!! important
This log file should be provided if you ask for support.
Depending on your setup the file could be accesible from the web interface alongside other logs
Depending on your setup the file could be accessible from the web interface alongside other logs
Mainsail | Fluidd
:-:|:-:
![m_logs](img/troubleshooting/logs_mainsail.png) | ![f_logs](img/troubleshooting/logs_fluidd.png)
if you can't find it in the web interface, use sftp to grab the log (for example Filezilla, WinSCP)
Located at `~/printer_data/logs`or in `/tmp/` if the former doesn't exists.
Located at `~/printer_data/logs`or in `/tmp/` if the former doesn't exist.
If KlipperScreen.log doesn't exist, run `systemctl status KlipperScreen`<br>
(or `journalctl -xe -u KlipperScreen`)
@ -25,154 +23,53 @@ If KlipperScreen.log doesn't exist, run `systemctl status KlipperScreen`<br>
Check the file `/var/log/Xorg.0.log` where you can find issues with the X server.
## Cannot open virtual Console
If you see this line in the logs:
If you see this line in the logs (`systemctl status KlipperScreen`):
```sh
xf86OpenConsole: Cannot open virtual console 2 (Permission denied)
```
* Run `cat /etc/X11/Xwrapper.config`
This should have the line `allowed_users=anybody` in it
* Run `cat /etc/group | grep tty`
If your username is not listed under that line, you need to add it with the following command:
```sh
usermod -a -G tty pi
```
(if your username is not 'pi' change 'pi' to your username)
Restart KlipperScreen:
```sh
sudo service KlipperScreen restart
```
If it's still failing as a last resort add `needs_root_rights=yes` to `/etc/X11/Xwrapper.config`:
```sh
sudo bash -c "echo needs_root_rights=yes>>/etc/X11/Xwrapper.config"
```
restart KS.
[Follow this steps](Troubleshooting/VC_ERROR.md)
## Screen shows console instead of KlipperScreen
If you have multiple framebuffers, you may need to fix the X11 configuration,
list the available framebuffers and check the current one:
You may see this line in the logs (`systemctl status KlipperScreen`):
```sh
ls /dev/fb*
cat /usr/share/X11/xorg.conf.d/99-fbturbo.conf | grep /dev/fb
KlipperScreen-start.sh: (EE) no screens found(EE)
```
If you more than one, try changing it:
```sh
sudo nano /usr/share/X11/xorg.conf.d/99-fbturbo.conf
```
for example: change `/dev/fb0` to `/dev/fb1`
Once you have saved that file, restart KlipperScreen.
```sh
sudo service KlipperScreen restart
```
If you have multiple hdmi ports try the other one
[Follow this steps](Troubleshooting/Showing_Console.md)
## Screen is all white or blank or no signal
If the screen never shows the console even during startup, Then it's tipically an improperly installed screen,
follow the manufacturer instructions on how to physically connect the screen and install the proper drivers.
If the screen never shows the console even during startup, Then it's typically an improperly installed screen,
## The screen starts flashing colors or stays all blue/white or shows 'No signal' when idle
You may see this line in the logs (`systemctl status KlipperScreen`):
```sh
KlipperScreen-start.sh: (EE) no screens found(EE)
```
[Follow this steps](Troubleshooting/Physical_Install.md)
## The screen shows colors or 'No signal' when idle
In KliperScreen settings find 'Screen DPMS' and turn it off.
Your screen doesn't seem to support turning off via software, the best you can do is to turn it all black.
## Touch not working on debian Bullseye
## Touch issues
Some dsi screens have issues where touch doesn't work with debian bullseye, the current fix
(at least until upstream is fixed) consist in changing the driver:
Run `raspi-config` > go to Advanced > GL Driver > select G2 and reboot.
[Follow this steps](Troubleshooting/Touch_issues.md)
![config](img/troubleshooting/gldriver.png)
## Network panel doesn't list WI-FI networks
*Or*:
manually edit `/boot/config.txt` and change:
```sh
dtoverlay=vc4-kms-v3d
```
to:
```sh
dtoverlay=vc4-fkms-v3d
```
and reboot, that should make the touch work, if your screen is rotated 180 degrees, then you may need to adjust
[the touch rotation](Hardware.md) as described in the Hardware page.
[Follow this steps](Troubleshooting/Network.md)
## OctoPrint
KlipperScreen was never intended to be used with OctoPrint, and there is no support for it.
## WiFi networks not listed (Using wpa_supplicant as backend)
This can be caused because of the user is not allowed to control the interface
* Edit `/etc/wpa_supplicant/wpa_supplicant.conf` and add this line if it's not there:
```
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
```
* Run `cat /etc/group | grep netdev`
If your username is not listed under that line, you need to add it with the following command:
```sh
usermod -a -G netdev pi
```
(if your username is not 'pi' change 'pi' to your username)
Then reboot the machine:
```sh
systemctl reboot
```
!!! tip
It's possible to just restart KlipperScreen and networking
## WiFi networks not listed (Using NetworkManager as backend)
`[wifi_nm.py:rescan()] [...] NetworkManager.wifi.scan request failed: not authorized`
If you see the above permission error in the log you may need to use polkit or disable it:
```sh
mkdir -p /etc/NetworkManager/conf.d
sudo nano /etc/NetworkManager/conf.d/any-user.conf
```
in the editor paste this:
```conf
[main]
auth-polkit=false
```
Then restart the service:
```sh
systemctl restart NetworkManager.service
```
!!! tip
It's possible to just restart KlipperScreen and NetworkManager
## Other issues
If you found an issue not listed here, or can't make it work, please provide all the log files

View File

@ -0,0 +1,50 @@
# Wi-Fi networks not listed
Check if network-manager is installed:
```
dpkg -s network-manager
```
if the response is the following:
```
dpkg-query: the package `network-manager' is not installed
```
go to [wpa_supplicant](wpa_supplicant.md)
if the response is the following:
```
Package: network-manager
Status: install ok installed
```
this line may appear in KlipperScreen.log:
`[wifi_nm.py:rescan()] [...] NetworkManager.wifi.scan request failed: not authorized`
in order to fix this polkit needs to be configured or disabled:
here is how to disable polkit for network-manager:
```sh
mkdir -p /etc/NetworkManager/conf.d
sudo nano /etc/NetworkManager/conf.d/any-user.conf
```
in the editor paste this:
```conf
[main]
auth-polkit=false
```
Then restart the service (or reboot):
```sh
systemctl restart NetworkManager.service
systemctl restart KlipperScreen.service
```

View File

@ -0,0 +1,28 @@
# Physical install issues
If the screen never shows the console even during startup, Then it's typically an improperly installed screen,
!!! important
It is advised follow the manufacturer instructions on how to physically connect the screen and install the proper drivers.
## Cable issues
* Check that the cable is inserted properly:
it shouldn't be loose, and in the case of DSI make sure the contacts face the right way
* If the touchscreen is connected via USB, try another port if available, if you are using a HUB try connecting the touch directly without the HUB.
* If the board has more than one HDMI try the other port
## Driver issues
Some screens need drivers installed the most common cases are:
### Waveshare
* [Waveshare Wiki](https://www.waveshare.com/wiki)
* [repo LCD-show](https://github.com/waveshare/LCD-show)
### Goodtft (generic/clones)
* [Goodtft Wiki](http://www.lcdwiki.com)
* [repo LCD-show](https://github.com/goodtft/LCD-show)
!!! critical
remember to add `lite` when installing. See [LCD-SHOW](Showing_console.md#lcd-show)

View File

@ -0,0 +1,66 @@
# Screen shows console instead of KlipperScreen
TODO:
- image of the console
- update for non fbturbo
If the screen is connected via HDMI and the board has more than one HDMI try the other port
## LCD-show
when using LCD-show repos to install screens add `lite` at the end to properly install the screen on the lite version of the os.
for example:
```
sudo ./LCD35-show lite
```
## Using wrong framebuffer
This is usually the result of not adding `lite` at the end of the command when installing a screen that requires LCD-show.
Follow [above](LCD-show) first if this is the case.
If you have multiple framebuffers, you may need to fix the X11 configuration,
list the available framebuffers and check the current one:
```sh
ls /dev/fb*
```
If you more than one, try changing it:
the file could be:
- 99-fbturbo.conf
- 99-fbusb.conf
- 99-fbdev.conf
check if one of those or similar exist with:
```sh
ls /usr/share/X11/xorg.conf.d/
```
For example if 99-fbturbo.conf is there then edit it:
```sh
sudo nano /usr/share/X11/xorg.conf.d/99-fbturbo.conf
```
for example: change `/dev/fb0` to `/dev/fb1`
!!! important
do `ls /dev/fb*` as said before to check if the other fb exists do not change it blindly
Once you have saved that file, restart KlipperScreen.
```sh
sudo service KlipperScreen restart
```
## FBturbo failing
in the system log (`sudo systemctl status KlipperScreen`) this appears:
`xinit[948]: /usr/lib/xorg/Xorg: symbol lookup error: /usr/lib/xorg/modules/drivers/fbturbo_drv.so: undefined symbol: shadowUpdatePackedWeak`
Fix it by removing fbturbo driver
`sudo apt purge xserver-xorg-video-fbturbo`

View File

@ -0,0 +1,101 @@
# Touchscreen issues
## Touch not working
Some DSI screens have issues where touch doesn't work with Debian Bullseye, or even in Debian Buster after an update, the current fix
(at least until upstream is fixed) consist in changing the driver:
manually edit `/boot/config.txt` and change:
```sh
dtoverlay=vc4-kms-v3d
```
to:
```sh
dtoverlay=vc4-fkms-v3d
```
reboot to apply changes.
if that doesn't fix it, try removing the line or comment it out
```
#dtoverlay=vc4-kms-v3d
#max_framebuffers=2
```
reboot to apply changes
If the screen is connected via USB It maybe a cable issue [See this section](Physical_Install.md#cable-issues)
## Touch rotation and matrix
If the touch works but it's not in the right place, it may need a transformation matrix.
First you will need your device name, on a terminal run:
```sh
DISPLAY=:0 xinput
```
Output:
```sh
⎡ Virtual core pointer id=2 [master pointer (3)]
⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)]
⎜ ↳ ADS7846 Touchscreen id=6 [slave pointer (2)]
⎣ Virtual core keyboard id=3 [master keyboard (2)]
↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)]
```
In this case the device is the ADS7846 Touchscreen, yours may be different
You can test a change by running:
```sh
DISPLAY=:0 xinput set-prop "<device name>" 'Coordinate Transformation Matrix' <matrix>
```
Where the matrix can be one of the following options:
* 0°: `1 0 0 0 1 0 0 0 1`
* 90° Clockwise: `0 -1 1 1 0 0 0 0 1`
* 90° Counter-Clockwise: `0 1 0 -1 0 1 0 0 1`
* 180° (Inverts X and Y): `-1 0 1 0 -1 1 0 0 1`
* invert Y: `-1 0 1 1 1 0 0 0 1`
* invert X: `-1 0 1 0 1 0 0 0 1`
* expand to twice the size horizontally: `0.5 0 0 0 1 0 0 0 1`
* compress horizontally:
it has been reported that the touch expands with non-hdmi screens because composite out is enabled when hdmi is unplugged.
if this is the case try adding `enable_tvout=0` to `/boot/config.txt` and reboot.
For example:
```sh
DISPLAY=:0 xinput set-prop "ADS7846 Touchscreen" 'Coordinate Transformation Matrix' -1 0 1 0 -1 1 0 0 1
```
To make this permanent, modify the file `/etc/udev/rules.d/51-touchscreen.rules` and add following line:
```sh
ACTION=="add", ATTRS{name}=="<device name>", ENV{LIBINPUT_CALIBRATION_MATRIX}="<matrix>"
```
As an alternative if the above doesn't work:
edit /usr/share/X11/xorg.conf.d/40-libinput.conf
for example:
```sh
Section "InputClass"
Identifier "libinput touchscreen catchall"
MatchIsTouchscreen "on"
MatchDevicePath "/dev/input/event*"
Driver "libinput"
Option "TransformationMatrix" "0 -1 1 1 0 0 0 0 1"
EndSection
```
More info about input transformation can be found in:
* [Ubuntu wiki InputCoordinateTransformation](https://wiki.ubuntu.com/X/InputCoordinateTransformation)
* [Libinput docs](https://wayland.freedesktop.org/libinput/doc/1.9.0/absolute_axes.html)

View File

@ -0,0 +1,31 @@
# Cannot open virtual Console
If you see this line in the logs:
```sh
xf86OpenConsole: Cannot open virtual console 2 (Permission denied)
```
* Run `cat /etc/X11/Xwrapper.config`
This should have the line `allowed_users=anybody` in it
* Run `cat /etc/group | grep tty`
If your username is not listed under that line, you need to add it with the following command:
```sh
usermod -a -G tty pi
```
(if your username is not 'pi' change 'pi' to your username)
Restart KlipperScreen:
```sh
sudo service KlipperScreen restart
```
If it's still failing as a last resort add `needs_root_rights=yes` to `/etc/X11/Xwrapper.config`:
```sh
sudo bash -c "echo needs_root_rights=yes>>/etc/X11/Xwrapper.config"
```
restart KS.

View File

@ -0,0 +1,27 @@
## wpa_supplicant
The user is not allowed to control the interface
* Edit `/etc/wpa_supplicant/wpa_supplicant.conf` and add this line if it's not there:
```
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
```
* Run `cat /etc/group | grep netdev`
If your username is not listed under that line, you need to add it with the following command:
```sh
usermod -a -G netdev pi
```
(if your username is not 'pi' change 'pi' to your username)
Then reboot the machine:
```sh
systemctl reboot
```
!!! tip
It's possible to just restart KlipperScreen and networking

View File

@ -15,13 +15,19 @@ nav:
- Macros: macros.md
- Android.md
- Thumbnails.md
- Troubleshooting.md
- Panels:
- Bed Level/Screws: Screws.md
- Job_status/Printing: Job_status.md
- Temperature: Temperature.md
- Z Calibrate: Zcalibrate.md
- Troubleshooting:
- First Steps/Log: Troubleshooting.md
- Network: Troubleshooting/Network.md
- Physical install: Troubleshooting/Physical_Install.md
- Showing Console: Troubleshooting/Showing_console.md
- Touch: Troubleshooting/Touch_issues.md
- Virtual Console Error: Troubleshooting/VC_ERROR.md
- Screenshots: Panels.md
- Panels:
- Bed Level/Screws: Panels/Screws.md
- Job_status/Printing: Panels/Job_status.md
- Temperature: Panels/Temperature.md
- Z Calibrate: Panels/Zcalibrate.md
- Theming.md
- Translations.md
- Breaking Changes: Changelog.md