165 lines
5.4 KiB
ReStructuredText
165 lines
5.4 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
Environment variables
|
|
=====================
|
|
|
|
The libcamera behaviour can be tuned through environment variables. This
|
|
document lists all the available variables and describes their usage.
|
|
|
|
List of variables
|
|
-----------------
|
|
|
|
LIBCAMERA_LOG_FILE
|
|
The custom destination for log output.
|
|
|
|
Example value: ``/home/{user}/camera_log.log``
|
|
|
|
LIBCAMERA_LOG_LEVELS
|
|
Configure the verbosity of log messages for different categories (`more <Log levels_>`__).
|
|
|
|
Example value: ``*:DEBUG``
|
|
|
|
LIBCAMERA_LOG_NO_COLOR
|
|
Disable coloring of log messages (`more <Notes about debugging_>`__).
|
|
|
|
LIBCAMERA_IPA_CONFIG_PATH
|
|
Define custom search locations for IPA configurations (`more <IPA configuration_>`__).
|
|
|
|
Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa``
|
|
|
|
LIBCAMERA_IPA_FORCE_ISOLATION
|
|
When set to a non-empty string, force process isolation of all IPA modules.
|
|
|
|
Example value: ``1``
|
|
|
|
LIBCAMERA_IPA_MODULE_PATH
|
|
Define custom search locations for IPA modules (`more <IPA module_>`__).
|
|
|
|
Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib``
|
|
|
|
LIBCAMERA_PIPELINES_MATCH_LIST
|
|
Define an ordered list of pipeline names to be used to match the media
|
|
devices in the system. The pipeline handler names used to populate the
|
|
variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the
|
|
source code.
|
|
|
|
Example value: ``rkisp1,simple``
|
|
|
|
LIBCAMERA_RPI_CONFIG_FILE
|
|
Define a custom configuration file to use in the Raspberry Pi pipeline handler.
|
|
|
|
Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml``
|
|
|
|
Further details
|
|
---------------
|
|
|
|
Notes about debugging
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The environment variables ``LIBCAMERA_LOG_FILE``, ``LIBCAMERA_LOG_LEVELS`` and
|
|
``LIBCAMERA_LOG_NO_COLOR`` are used to modify the default configuration of the
|
|
libcamera logger.
|
|
|
|
By default, libcamera logs all messages to the standard error (std::cerr).
|
|
Messages are colored by default depending on the log level. Coloring can be
|
|
disabled by setting the ``LIBCAMERA_LOG_NO_COLOR`` environment variable.
|
|
|
|
The default log destination can also be directed to a file by setting the
|
|
``LIBCAMERA_LOG_FILE`` environment variable to the log file name. This also
|
|
disables coloring.
|
|
|
|
Log levels are controlled through the ``LIBCAMERA_LOG_LEVELS`` variable, which
|
|
accepts a comma-separated list of 'category:level' pairs.
|
|
|
|
The `level <Log levels_>`__ part is mandatory and can either be specified by
|
|
name or by numerical index associated with each level.
|
|
|
|
The optional `category <Log categories_>`__ is a string matching the categories
|
|
defined by each file in the source base using the logging infrastructure. It
|
|
can include a wildcard ('*') character at the end to match multiple categories.
|
|
|
|
For more information refer to the `API documentation <https://libcamera.org/api-html/log_8h.html#details>`__.
|
|
|
|
Examples:
|
|
|
|
Enable full debug output to a separate file, for every `category <Log categories_>`__
|
|
within a local environment:
|
|
|
|
.. code:: bash
|
|
|
|
:~$ LIBCAMERA_LOG_FILE='/tmp/example_log.log' \
|
|
LIBCAMERA_LOG_LEVELS=0 \
|
|
cam --list
|
|
|
|
Enable full debug output for the categories ``Camera`` and ``V4L2`` within a
|
|
global environment:
|
|
|
|
.. code:: bash
|
|
|
|
:~$ export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,V4L2:DEBUG'
|
|
:~$ cam --list
|
|
|
|
Log levels
|
|
~~~~~~~~~~
|
|
|
|
This is the list of available log levels, notice that all levels below
|
|
the chosen one are printed, while those above are discarded.
|
|
|
|
- DEBUG (0)
|
|
- INFO (1)
|
|
- WARN (2)
|
|
- ERROR (3)
|
|
- FATAL (4)
|
|
|
|
Example:
|
|
If you choose WARN (2), you will be able to see WARN (2), ERROR (3) and FATAL (4)
|
|
but not DEBUG (0) and INFO (1).
|
|
|
|
Log categories
|
|
~~~~~~~~~~~~~~
|
|
|
|
Every category represents a specific area of the libcamera codebase,
|
|
the names can be located within the source code, for example:
|
|
`src/libcamera/camera_manager.cpp <https://git.libcamera.org/libcamera/libcamera.git/tree/src/libcamera/camera_manager.cpp#n35>`__
|
|
|
|
.. code:: cpp
|
|
|
|
LOG_DEFINE_CATEGORY(Camera)
|
|
|
|
There are two available macros used to assign a category name to a part of the
|
|
libcamera codebase:
|
|
|
|
LOG_DEFINE_CATEGORY
|
|
This macro is required, in order to use the ``LOGC`` macro for a particular
|
|
category. It can only be used once for each category. If you want to create
|
|
log messages within multiple compilation units for the same category utilize
|
|
the ``LOG_DECLARE_CATEGORY`` macro, in every file except the definition file.
|
|
LOG_DECLARE_CATEGORY
|
|
Used for sharing an already defined category between multiple separate
|
|
compilation units.
|
|
|
|
Both macros have to be used within the libcamera namespace of the C++ source
|
|
code.
|
|
|
|
IPA configuration
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
IPA modules use configuration files to store parameters. The format and
|
|
contents of the configuration files is specific to the IPA module. They usually
|
|
contain tuning parameters for the algorithms, in JSON format.
|
|
|
|
The ``LIBCAMERA_IPA_CONFIG_PATH`` variable can be used to specify custom
|
|
storage locations to search for those configuration files.
|
|
|
|
`Examples <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa/rpi/vc4/data>`__
|
|
|
|
IPA module
|
|
~~~~~~~~~~
|
|
|
|
In order to locate the correct IPA module for your hardware, libcamera gathers
|
|
existing IPA modules from multiple locations. The default locations for this
|
|
operation are the installed system path (for example on Debian:
|
|
``/usr/local/x86_64-pc-linux-gnu/libcamera``) and the build directory.
|
|
With the ``LIBCAMERA_IPA_MODULE_PATH``, you can specify a non-default location
|
|
to search for IPA modules.
|