mirror of
https://github.com/QIDITECH/klipper.git
synced 2026-01-30 15:38:42 +03:00
klipper update
This commit is contained in:
Rainboooom
280
docs/Debugging.md
Normal file
280
docs/Debugging.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# Debugging
|
||||
|
||||
This document describes some of the Klipper debugging tools.
|
||||
|
||||
## Running the regression tests
|
||||
|
||||
The main Klipper GitHub repository uses "github actions" to run a
|
||||
series of regression tests. It can be useful to run some of these
|
||||
tests locally.
|
||||
|
||||
The source code "whitespace check" can be run with:
|
||||
```
|
||||
./scripts/check_whitespace.sh
|
||||
```
|
||||
|
||||
The Klippy regression test suite requires "data dictionaries" from
|
||||
many platforms. The easiest way to obtain them is to
|
||||
[download them from github](https://github.com/Klipper3d/klipper/issues/1438).
|
||||
Once the data dictionaries are downloaded, use the following to run
|
||||
the regression suite:
|
||||
```
|
||||
tar xfz klipper-dict-20??????.tar.gz
|
||||
~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test
|
||||
```
|
||||
|
||||
## Manually sending commands to the micro-controller
|
||||
|
||||
Normally, the host klippy.py process would be used to translate gcode
|
||||
commands to Klipper micro-controller commands. However, it's also
|
||||
possible to manually send these MCU commands (functions marked with
|
||||
the DECL_COMMAND() macro in the Klipper source code). To do so, run:
|
||||
|
||||
```
|
||||
~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial
|
||||
```
|
||||
|
||||
See the "HELP" command within the tool for more information on its
|
||||
functionality.
|
||||
|
||||
Some command-line options are available. For more information run:
|
||||
`~/klippy-env/bin/python ./klippy/console.py --help`
|
||||
|
||||
## Translating gcode files to micro-controller commands
|
||||
|
||||
The Klippy host code can run in a batch mode to produce the low-level
|
||||
micro-controller commands associated with a gcode file. Inspecting
|
||||
these low-level commands is useful when trying to understand the
|
||||
actions of the low-level hardware. It can also be useful to compare
|
||||
the difference in micro-controller commands after a code change.
|
||||
|
||||
To run Klippy in this batch mode, there is a one time step necessary
|
||||
to generate the micro-controller "data dictionary". This is done by
|
||||
compiling the micro-controller code to obtain the **out/klipper.dict**
|
||||
file:
|
||||
|
||||
```
|
||||
make menuconfig
|
||||
make
|
||||
```
|
||||
|
||||
Once the above is done it is possible to run Klipper in batch mode
|
||||
(see [installation](Installation.md) for the steps necessary to build
|
||||
the python virtual environment and a printer.cfg file):
|
||||
|
||||
```
|
||||
~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict
|
||||
```
|
||||
|
||||
The above will produce a file **test.serial** with the binary serial
|
||||
output. This output can be translated to readable text with:
|
||||
|
||||
```
|
||||
~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt
|
||||
```
|
||||
|
||||
The resulting file **test.txt** contains a human readable list of
|
||||
micro-controller commands.
|
||||
|
||||
The batch mode disables certain response / request commands in order
|
||||
to function. As a result, there will be some differences between
|
||||
actual commands and the above output. The generated data is useful for
|
||||
testing and inspection; it is not useful for sending to a real
|
||||
micro-controller.
|
||||
|
||||
## Motion analysis and data logging
|
||||
|
||||
Klipper supports logging its internal motion history, which can be
|
||||
later analyzed. To use this feature, Klipper must be started with the
|
||||
[API Server](API_Server.md) enabled.
|
||||
|
||||
Data logging is enabled with the `data_logger.py` tool. For example:
|
||||
```
|
||||
~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog
|
||||
```
|
||||
|
||||
This command will connect to the Klipper API Server, subscribe to
|
||||
status and motion information, and log the results. Two files are
|
||||
generated - a compressed data file and an index file (eg,
|
||||
`mylog.json.gz` and `mylog.index.gz`). After starting the logging, it
|
||||
is possible to complete prints and other actions - the logging will
|
||||
continue in the background. When done logging, hit `ctrl-c` to exit
|
||||
from the `data_logger.py` tool.
|
||||
|
||||
The resulting files can be read and graphed using the `motan_graph.py`
|
||||
tool. To generate graphs on a Raspberry Pi, a one time step is
|
||||
necessary to install the "matplotlib" package:
|
||||
```
|
||||
sudo apt-get update
|
||||
sudo apt-get install python-matplotlib
|
||||
```
|
||||
However, it may be more convenient to copy the data files to a desktop
|
||||
class machine along with the Python code in the `scripts/motan/`
|
||||
directory. The motion analysis scripts should run on any machine with
|
||||
a recent version of [Python](https://python.org) and
|
||||
[Matplotlib](https://matplotlib.org/) installed.
|
||||
|
||||
Graphs can be generated with a command like the following:
|
||||
```
|
||||
~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png
|
||||
```
|
||||
|
||||
One can use the `-g` option to specify the datasets to graph (it takes
|
||||
a Python literal containing a list of lists). For example:
|
||||
```
|
||||
~/klipper/scripts/motan/motan_graph.py mylog -g '[["trapq(toolhead,velocity)"], ["trapq(toolhead,accel)"]]'
|
||||
```
|
||||
|
||||
The list of available datasets can be found using the `-l` option -
|
||||
for example:
|
||||
```
|
||||
~/klipper/scripts/motan/motan_graph.py -l
|
||||
```
|
||||
|
||||
It is also possible to specify matplotlib plot options for each
|
||||
dataset:
|
||||
```
|
||||
~/klipper/scripts/motan/motan_graph.py mylog -g '[["trapq(toolhead,velocity)?color=red&alpha=0.4"]]'
|
||||
```
|
||||
Many matplotlib options are available; some examples are "color",
|
||||
"label", "alpha", and "linestyle".
|
||||
|
||||
The `motan_graph.py` tool supports several other command-line
|
||||
options - use the `--help` option to see a list. It may also be
|
||||
convenient to view/modify the
|
||||
[motan_graph.py](../scripts/motan/motan_graph.py) script itself.
|
||||
|
||||
The raw data logs produced by the `data_logger.py` tool follow the
|
||||
format described in the [API Server](API_Server.md). It may be useful
|
||||
to inspect the data with a Unix command like the following:
|
||||
`gunzip < mylog.json.gz | tr '\03' '\n' | less`
|
||||
|
||||
## Generating load graphs
|
||||
|
||||
The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth,
|
||||
micro-controller load, and host buffer load. It can be useful to graph
|
||||
these statistics after a print.
|
||||
|
||||
To generate a graph, a one time step is necessary to install the
|
||||
"matplotlib" package:
|
||||
|
||||
```
|
||||
sudo apt-get update
|
||||
sudo apt-get install python-matplotlib
|
||||
```
|
||||
|
||||
Then graphs can be produced with:
|
||||
|
||||
```
|
||||
~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png
|
||||
```
|
||||
|
||||
One can then view the resulting **loadgraph.png** file.
|
||||
|
||||
Different graphs can be produced. For more information run:
|
||||
`~/klipper/scripts/graphstats.py --help`
|
||||
|
||||
## Extracting information from the klippy.log file
|
||||
|
||||
The Klippy log file (/tmp/klippy.log) also contains debugging
|
||||
information. There is a logextract.py script that may be useful when
|
||||
analyzing a micro-controller shutdown or similar problem. It is
|
||||
typically run with something like:
|
||||
|
||||
```
|
||||
mkdir work_directory
|
||||
cd work_directory
|
||||
cp /tmp/klippy.log .
|
||||
~/klipper/scripts/logextract.py ./klippy.log
|
||||
```
|
||||
|
||||
The script will extract the printer config file and will extract MCU
|
||||
shutdown information. The information dumps from an MCU shutdown (if
|
||||
present) will be reordered by timestamp to assist in diagnosing cause
|
||||
and effect scenarios.
|
||||
|
||||
## Testing with simulavr
|
||||
|
||||
The [simulavr](http://www.nongnu.org/simulavr/) tool enables one to
|
||||
simulate an Atmel ATmega micro-controller. This section describes how
|
||||
one can run test gcode files through simulavr. It is recommended to
|
||||
run this on a desktop class machine (not a Raspberry Pi) as it does
|
||||
require significant cpu to run efficiently.
|
||||
|
||||
To use simulavr, download the simulavr package and compile with python
|
||||
support. Note that the build system may need to have some packages (such as
|
||||
swig) installed in order to build the python module.
|
||||
|
||||
```
|
||||
git clone git://git.savannah.nongnu.org/simulavr.git
|
||||
cd simulavr
|
||||
make python
|
||||
make build
|
||||
```
|
||||
Make sure a file like **./build/pysimulavr/_pysimulavr.*.so** is present
|
||||
after the above compilation:
|
||||
```
|
||||
ls ./build/pysimulavr/_pysimulavr.*.so
|
||||
```
|
||||
This commmand should report a specific file (e.g.
|
||||
**./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so**) and
|
||||
not an error.
|
||||
|
||||
If you are on a Debian-based system (Debian, Ubuntu, etc.) you can
|
||||
install the following packages and generate *.deb files for system-wide
|
||||
installation of simulavr:
|
||||
```
|
||||
sudo apt update
|
||||
sudo apt install g++ make cmake swig rst2pdf help2man texinfo
|
||||
make cfgclean python debian
|
||||
sudo dpkg -i build/debian/python3-simulavr*.deb
|
||||
```
|
||||
|
||||
To compile Klipper for use in simulavr, run:
|
||||
|
||||
```
|
||||
cd /path/to/klipper
|
||||
make menuconfig
|
||||
```
|
||||
|
||||
and compile the micro-controller software for an AVR atmega644p and
|
||||
select SIMULAVR software emulation support. Then one can compile
|
||||
Klipper (run `make`) and then start the simulation with:
|
||||
|
||||
```
|
||||
PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf
|
||||
```
|
||||
Note that if you have installed python3-simulavr system-wide, you do
|
||||
not need to set `PYTHONPATH`, and can simply run the simulator as
|
||||
```
|
||||
./scripts/avrsim.py out/klipper.elf
|
||||
```
|
||||
|
||||
Then, with simulavr running in another window, one can run the
|
||||
following to read gcode from a file (eg, "test.gcode"), process it
|
||||
with Klippy, and send it to Klipper running in simulavr (see
|
||||
[installation](Installation.md) for the steps necessary to build the
|
||||
python virtual environment):
|
||||
|
||||
```
|
||||
~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v
|
||||
```
|
||||
|
||||
### Using simulavr with gtkwave
|
||||
|
||||
One useful feature of simulavr is its ability to create signal wave
|
||||
generation files with the exact timing of events. To do this, follow
|
||||
the directions above, but run avrsim.py with a command-line like the
|
||||
following:
|
||||
|
||||
```
|
||||
PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT
|
||||
```
|
||||
|
||||
The above would create a file **avrsim.vcd** with information on each
|
||||
change to the GPIOs on PORTA and PORTB. This could then be viewed
|
||||
using gtkwave with:
|
||||
|
||||
```
|
||||
gtkwave avrsim.vcd
|
||||
```
|
||||
Reference in New Issue
Block a user