diff --git a/doc/distribution_linux.md b/doc/distribution_linux.md index 422e36a01b..fa6c18052f 100644 --- a/doc/distribution_linux.md +++ b/doc/distribution_linux.md @@ -1,7 +1,8 @@ # Linux Distribution **Intel® RealSense™ SDK 2.0** provides installation packages in [`dpkg`](https://en.wikipedia.org/wiki/Dpkg) format for Ubuntu 16 LTS\*. -\* The Realsense DKMS driver package (`realsense-uvcvideo`) currently supports Ubuntu 16 with LTS kernels 4.4 and 4.10. +\* The Realsense [DKMS](https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support) kernel drivers package (`librealsense2-dkms`) supports Ubuntu LTS kernels 4.4, 4.10 and 4.13. + > To build the project from source, please follow steps described [here](./installation.md) @@ -18,8 +19,9 @@ It is recommended to backup `/etc/apt/sources.list.d/realsense-public.list` file `sudo apt-get update` - In order to run demos install: - `sudo apt-get install realsense-uvcvideo` + `sudo apt-get install librealsense2-dkms` `sudo apt-get install librealsense2-utils` + The above two lines will deploy librealsense2 udev rules, kernel drivers, runtime library and executable demos and tools. Reconnect the Intel RealSense depth camera and run: `realsense-viewer` - Developers shall install additional packages: @@ -28,10 +30,6 @@ It is recommended to backup `/etc/apt/sources.list.d/realsense-public.list` file With `dev` package installed, you can compile an application with **librealsense** using `g++ -std=c++11 filename.cpp -lrealsense2` or an IDE of your choice. - Complete the installation by performing - `reboot` - to reload the kernel with modules provided by DKMS. - Verify that the kernel is updated : `modinfo uvcvideo | grep "version:"` should include `realsense` string @@ -49,12 +47,12 @@ The packages and their respective content are listed below: Name | Content | Depends on | -------- | ------------ | ---------------- | -librealsense2-udev-rules | Manages the devices permissions configuration for | - -realsense-uvcvideo | DKMS package for Depth cameras-specific kernel extensions | librealsense2-udev-rules +librealsense2-udev-rules | Configures RealSense device permissions on kernel level | - +librealsense2-dkms | DKMS package for Depth cameras-specific kernel extensions | librealsense2-udev-rules librealsense2 | RealSense™ SDK runtime (.so) and configuration files | librealsense2-udev-rules librealsense2-utils | Demos and tools available as a part of RealSense™ SDK | librealsense2 librealsense2-dev | Header files and symbolic link for developers | librealsense2 librealsense2-dbg | Debug symbols for developers | librealsense2 -**Note** The packages include binaries only. +**Note** The packages include binaries and configuration files only. Use the github repository to obtain the source code. diff --git a/doc/installation.md b/doc/installation.md index 19871c018f..03f3d6559f 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,36 +1,68 @@ -# Linux Installation +# Linux Ubuntu Installation -**Note:** Due to the USB 3.0 translation layer between native hardware and virtual machine, the *librealsense* team does not support installation in a VM. If you do choose to try it, we recommend using VMware Workstation Player, and not Oracle VirtualBox for proper emulation of the USB3 controller. +**Note:** Due to the USB 3.0 translation layer between native hardware and virtual machine, the *librealsense* team does not support installation in a VM. If you do choose to try it, we recommend using VMware Workstation Player, and not Oracle VirtualBox for proper emulation of the USB3 controller. -## 3rd-party dependencies +## Ubuntu Build Dependencies -* **Note:** On Ubuntu 16.04 LTS, make sure you have git and cmake installed: `sudo apt-get install git cmake3` +Make sure to have git and cmake installed as these are required for *librelasense* build: + `sudo apt-get install git cmake3` -**Important:** Several scripts below invoke `wget, git, add-apt-repository` which may be blocked by router settings or a firewall. Infrequently, apt-get mirrors or repositories may also timeout. For *librealsense* users behind an enterprise firewall, configuring the system-wide Ubuntu proxy generally resolves most timeout issues. +Several scripts below invoke `wget, git, add-apt-repository` which may be blocked by router settings or a firewall. Infrequently, apt-get mirrors or repositories may also timeout. For *librealsense* users behind an enterprise firewall, configuring the system-wide Ubuntu proxy generally resolves most timeout issues. -## Make Ubuntu Up-to-date -1. Update Ubuntu distribution, including getting the latest stable kernel - * `sudo apt-get update && sudo apt-get upgrade && sudo apt-get dist-upgrade`
+## Prerequisites +**Important:** Running RealSense Depth Cameras on Linux requires patching and inserting modified kernel drivers. Some OEM/Vendors choose to lock the kernel for modifications. Unlocking this capability may requires to modify BIOS settings - **Note:** On stock Ubuntu 14 LTS systems with Kernel prior to 4.4.0-04 the basic *apt-get upgrade* command is not sufficient to bring the distribution to the latest recommended baseline. On those systems use: `sudo apt-get install --install-recommends linux-generic-lts-xenial xserver-xorg-core-lts-xenial xserver-xorg-lts-xenial xserver-xorg-video-all-lts-xenial xserver-xorg-input-all-lts-xenial libwayland-egl1-mesa-lts-xenial `
+ **Make Ubuntu Up-to-date:** + 1. Update Ubuntu distribution, including getting the latest stable kernel + * `sudo apt-get update && sudo apt-get upgrade && sudo apt-get dist-upgrade`
+ **Note:** On stock Ubuntu 14 LTS systems with Kernel prior to 4.4.0-04 the basic *apt-get upgrade* command is not sufficient to bring the distribution to the latest recommended baseline. On those systems use: `sudo apt-get install --install-recommends linux-generic-lts-xenial xserver-xorg-core-lts-xenial xserver-xorg-lts-xenial xserver-xorg-video-all-lts-xenial xserver-xorg-input-all-lts-xenial libwayland-egl1-mesa-lts-xenial `
- * Check the kernel version using `uname -r` and note the exact Kernel version being installed (4.4.0-XX or 4.8.0-XX) for the next step.
+ * Update OS Boot and reboot to enforce the correct kernel selection with `sudo update-grub && sudo reboot`
- * Update OS Boot Menu and reboot to enforce the correct kernel selection with `sudo update-grub && sudo reboot`
+ * Interrupt the boot process at Grub2 Boot Menu -> "Advanced Options for Ubuntu" and select the kernel version installed in the previous step. Press and hold SHIFT if the Boot menu is not presented. + * Complete the boot, login and verify that a supported kernel version (4.4.0-.., 4.8.0-.., 4.10.0-.. or 4.13.0-.. as of Feb 2018) is in place with `uname -r` - * When rebooting interrupt the boot process at Grub2 Boot Menu -> "Advanced Options for Ubuntu" and select the kernel version installed in the previous step. - * Complete the boot, login and verify that the required kernel version (4.4.0-79 or 4.8.0-54 as of June 17th 2017) is in place with `uname -r` -2. Install the packages required for *librealsense* build: - * *libusb-1.0*, *pkg-config* and *libgtk-3*: `sudo apt-get install libusb-1.0-0-dev pkg-config libgtk-3-dev`. - * **Note:** glfw3 and gtk is only required if you plan to build the example code, not for the *librealsense* core library. +**Video4Linux backend preparation:** + 1. Ensure no Intel RealSense cameras are plugged in. - * *glfw3*: + 2. Install *openssl* package required for kernel module build:
+ * `sudo apt-get install libssl-dev`
+ + 3. Install udev rules located in librealsense source directory:
+ * `sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/` + * `sudo udevadm control --reload-rules && udevadm trigger` + + 4. Build and apply patched kernel modules for
+ * **Ubuntu 14/16 LTS** + The script will download, patch and build several kernel modules (drivers).
+ Then it will attempt to insert the patched module instead of the active one. If failed + the original uvc module will be preserved. + * `./scripts/patch-realsense-ubuntu-xenial.sh`
+ * **Intel® Joule™ with Ubuntu** + Based on the custom kernel provided by Canonical Ltd. + * `./scripts/patch-realsense-ubuntu-xenial-joule.sh`
+ * **Arch-based distributions** + * You need to install the [base-devel](https://www.archlinux.org/groups/x86_64/base-devel/) package group. + * You also need to install the matching linux-headers as well (i.e.: linux-lts-headers for the linux-lts kernel).
+ * Navigate to the scripts folder: `cd ./scripts/`
+ * Then run the following script to patch the uvc module: `./patch-arch.sh`
+ + * Check installation by examining the patch-generated log as well as inspecting the latest entries in kernel log: + `sudo dmesg | tail -n 50`
+ The log should indicate that a new uvcvideo driver has been registered. + Refer to the "troubleshooting" chapter in case of errors/warning reports. + + 5. Install the packages required for *librealsense* build: + *libusb-1.0*, *pkg-config* and *libgtk-3*: + `sudo apt-get install libusb-1.0-0-dev pkg-config libgtk-3-dev`. + **Note:** glfw3 and gtk are only required if you plan to build the examples, not for the *librealsense* core library. + + *glfw3*: * On Ubuntu 16.04 install glfw3 via `sudo apt-get install libglfw3-dev` * On Ubuntu 14.04 or when running of Ubuntu 16.04 live-disk, please use `./scripts/install_glfw3.sh` -3. Library Build Process
- *librealsense* employs CMake as a cross-platform build and project management system. +## Building librealsense2 SDK * On Ubuntu 14.04, update your build toolchain to *gcc-5*: * `sudo add-apt-repository ppa:ubuntu-toolchain-r/test` * `sudo apt-get update` @@ -44,7 +76,7 @@ * Navigate to *librealsense* root directory and run `mkdir build && cd build`
* Run CMake: - * `cmake ../` - The default build is set to produce the core shared object and unit-tests binaries
+ * `cmake ../` - The default build is set to produce the core shared object and unit-tests binaries in Debug mode. Use `-D CMAKE_BUILD_TYPE=release` to build with optimizations.
* `cmake ../ -DBUILD_EXAMPLES=true` - Builds *librealsense* along with the demos and tutorials
* `cmake ../ -DBUILD_EXAMPLES=true -DBUILD_GRAPHICAL_EXAMPLES=false` - For systems without OpenGL or X11 build only textual examples
@@ -53,42 +85,14 @@ The shared object will be installed in `/usr/local/lib`, header files in `/usr/local/include`
The demos, tutorials and tests will be located in `/usr/local/bin`
**Tip:** Use *`make -jX`* for parallel compilation, where *`X`* stands for the number of CPU cores available:
`sudo make uninstall && make clean && make -j8 && sudo make install`
- This enhancement will significantly improve build time. The side-effect, however, is that it may cause a low-end platform to hang randomly
+ This enhancement may significantly improve the build time. The side-effect, however, is that it may cause a low-end platform to hang randomly
**Note:** Linux build configuration is presently configured to use the V4L2 backend by default.
**Note:** If you encounter the following error during compilation `gcc: internal compiler error` it might indicate that you do not have enough memory or swap space on your machine. Try closing memory consuming applications, and if you are running inside a VM increase available RAM to at least 2 GB. -4. Install IDE (Optional): + 2. Install IDE (Optional): We use QtCreator as an IDE for Linux development on Ubuntu * Follow the [link](https://wiki.qt.io/Install_Qt_5_on_Ubuntu) for QtCreator5 installation -## Video4Linux backend preparation -**Note:** Running RealSense Depth Cameras on Linux requires applying patches to kernel modules.
-Ensure no Intel RealSense cameras are plugged into the system before beginning.
-1. Install udev rules located in librealsense source directory:
- * `sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/` - * `sudo udevadm control --reload-rules && udevadm trigger` - -2. Install *openssl* package required for kernel module build:
- * `sudo apt-get install libssl-dev`
- -3. Next, build the patched module for the desired machine configuration.
- * **Ubuntu 14/16 LTS** - The script will download, patch and build the uvc kernel module from source.
- Then it will attempt to insert the patched module instead of the active one. If failed - the original uvc module will be preserved. - * `./scripts/patch-realsense-ubuntu-xenial.sh`
- * **Intel® Joule™ with Ubuntu** - Based on the custom kernel provided by Canonical Ltd. - * `./scripts/patch-realsense-ubuntu-xenial-joule.sh`
- * **Arch-based distributions** - * You need to install the [base-devel](https://www.archlinux.org/groups/x86_64/base-devel/) package group. - * You also need to install the matching linux-headers as well (i.e.: linux-lts-headers for the linux-lts kernel).
- * Navigate to the scripts folder: `cd ./scripts/`
- * Then run the following script to patch the uvc module: `./patch-arch.sh`
- -4. Check installation by examining the latest entries in kernel log: - * `sudo dmesg | tail -n 50`
- The log should indicate that a new uvcvideo driver has been registered. If any errors have been noted, first attempt the patching process again, and then file an issue if not successful on the second attempt (and make sure to copy the specific error in dmesg). ## Troubleshooting Installation and Patch-related Issues diff --git a/include/librealsense2/rs.h b/include/librealsense2/rs.h index b479b0dd95..5561796b8e 100644 --- a/include/librealsense2/rs.h +++ b/include/librealsense2/rs.h @@ -24,7 +24,7 @@ extern "C" { #define RS2_API_MAJOR_VERSION 2 #define RS2_API_MINOR_VERSION 10 -#define RS2_API_PATCH_VERSION 0 +#define RS2_API_PATCH_VERSION 1 #define RS2_API_BUILD_VERSION 0 #define STRINGIFY(arg) #arg diff --git a/package.xml b/package.xml index d7940601a0..83fd32a8a5 100644 --- a/package.xml +++ b/package.xml @@ -7,7 +7,7 @@ librealsense2 - 2.10.0 + 2.10.1 Library for capturing data from the Intel(R) RealSense(TM) SR300 and D400 cameras. This effort was initiated to better support researchers, creative coders, and app developers in domains such as robotics, virtual reality, and the internet of things. Several often-requested features of RealSense(TM); devices are implemented in this project, including multi-camera capture.