From dffd818a42fbcc424d5a60a673dda0ab82f61051 Mon Sep 17 00:00:00 2001 From: Konstantin Eliseev <1deaglea@gmail.com> Date: Fri, 25 Jan 2019 18:32:04 +0300 Subject: [PATCH 1/3] New EN Articles 9 new EN articles --- docs/en/SUMMARY.md | 18 +- docs/en/frames.md | 16 ++ docs/en/gcs_bridge.md | 69 ++++++++ docs/en/mavros.md | 55 ++++++ docs/en/network.md | 319 +++++++++++++++++++++++++++++++++++ docs/en/rc.md | 56 +++++++ docs/en/ros.md | 106 ++++++++++++ docs/en/simple_offboard.md | 321 ++++++++++++++++++++++++++++++++++++ docs/en/web_video_server.md | 57 +++++++ 9 files changed, 1015 insertions(+), 2 deletions(-) create mode 100644 docs/en/frames.md create mode 100644 docs/en/gcs_bridge.md create mode 100644 docs/en/mavros.md create mode 100644 docs/en/network.md create mode 100644 docs/en/rc.md create mode 100644 docs/en/ros.md create mode 100644 docs/en/simple_offboard.md create mode 100644 docs/en/web_video_server.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 113ee45e..d95ab2c7 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -14,7 +14,6 @@ * [Soldering safety](tb.md) * [Connecting GPS](gps.md) * [Flight modes](modes.md) -* [UART settings](uart.md) * [Pixhawk / Pixracer Firmware](firmware.md) * [PX4 Parameters](px4_parameters.md) * [PID Setup](calibratePID.md) @@ -22,4 +21,19 @@ * [RPi Image](microsd_images.md) * [RPi Connection to the Pixhawk](connection.md) * [Wi-Fi connection](wifi.md) -* [SSH access](ssh.md) \ No newline at end of file +* [Configuring Wi-Fi](network.md) +* [Using QGroundControl via Wi-Fi](gcs_bridge.md) +* [Controlling Clever from a smartphone](rc.md) +* [UART settings](uart.md) +* [Viewing images from cameras](web_video_server.md) +* [Coordinate systems (frames)](frames.md) +* [ROS](ros.md) +* [MAVROS](mavros.md) +* [Simple offboard](simple_offboard.md) + + + + + + + diff --git a/docs/en/frames.md b/docs/en/frames.md new file mode 100644 index 00000000..1722725b --- /dev/null +++ b/docs/en/frames.md @@ -0,0 +1,16 @@ +Coordinate systems (frames) +=== + +> **Note** Documentation for the [image](microsd_images.md), versions, starting with **0.15**. For older versions refer to [documentation for version **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/frames.md). + +![Clever coordinates systems (TF2)](../assets/frames.png) + +Main frames in package `clever`: + +* `map` coordinates relative to the point of flight controller initialization: the white grid in the illustration; +* `base_link` — coordinates relative to the quadcopter: schematic image of the quadcopter in the illustration; +* `body` — coordinates relative to the quadcopter regardless of pitch and roll: red, blue and green lines in the illustration. + +> **Hint** In accordance with [the agreement](http://www.ros.org/reps/rep-0103.html), for frames associated with the copter, the X-axis directed forward, Y – to the left, and Z – up. + +More clearly, 3D visualization of the coordinate systems can be viewed using [rviz](rviz.md). \ No newline at end of file diff --git a/docs/en/gcs_bridge.md b/docs/en/gcs_bridge.md new file mode 100644 index 00000000..202844ff --- /dev/null +++ b/docs/en/gcs_bridge.md @@ -0,0 +1,69 @@ +Using QGroundControl via Wi-Fi +=== + +![QGroundControl](../assets/qground.png) + +You can monitor, control, calibrate and configure the flight controller of the quadcopter using QGroundControl via Wi-Fi. +This requires [connecting to Wi-Fi](Wi-Fi.md) of the `CLEVER-xxxx` network. + +After that, in the Clever launch-file `/home/pi/catkin_ws/src/clever/clever/launch/clever.launch`, choose one of the preconfigured bridge modes. + +After editing the launch-file, restart the clever service: + +```(bash) +sudo systemctl restart clever +``` + +TCP bridge +--- + +Change parameter `gcs_bridge` in the launch file: + +```xml + +``` + +Then in the QGroundControl program, choose Application Settings > Comm Links > Add. Create a connection with the following settings: + +![QGroundControl TCP connection](../assets/bridge_tcp.png) + +Then choose "Clever" from the list of connections, and click "Connect". + +UDP bridge (with automated connection) +--- + +Change parameter `gcs_bridge` in the launch file: + +```xml + +``` + +After opening the QGroundControl application, the connection should be established automatically. + +UDP bridge (without automated connection) +--- + +Change parameter `gcs_bridge` in the launch file: + +```xml + +``` + +Then in the QGroundControl program, choose Application Settings > Comm Links > Add. Create a connection with the following settings: + +![QGroundControl UDP connection](../assets/bridge_udp.png) + +Then choose "CLEVER" from the list of connections, and click "Connect". + +UDP broadcast bridge +--- + +> **Hint** The feature of the UDP broadcast bridge is the ability to view drone telemetry simultaneously from multiple devices (e.g., a phone and a PC). It is also well suited for devices networking using a router. + +Change parameter `gcs_bridge` in the launch file: + +```xml + +``` + +After opening the QGroundControl application, the connection should be established automatically. \ No newline at end of file diff --git a/docs/en/mavros.md b/docs/en/mavros.md new file mode 100644 index 00000000..a02af712 --- /dev/null +++ b/docs/en/mavros.md @@ -0,0 +1,55 @@ +# MAVROS + +Main documentation: [http://wiki.ros.org/mavros](http://wiki.ros.org/mavros) + +MAVROS \(MAVLink + ROS\) is a package for ROS that provides the possibility of controlling drones via the [MAVLink] protocol (mavlink.md). MAVROS supports flight stacks PX4 and APM. Communication is established via UART, USB, TCP or UDP. + +MAVROS subscribes to certain ROS topics while waiting for commands, publishes telemetry to other topics, and provides services. + +The MAVROS node is automatically started in the launch-file of Clever. For [setting the type of connection] (connection.md), see the `fcu_conn` argument. + +> **Hint** Simplified interaction with the copter may be with the use of the [`simple_offboard`] package (simple_offboard.md). + + + +> **Note** In the `clever` package, some MAVROS plugins are disabled (to save resources). For more information, see the `plugin_blacklist` parameter in file `/home/pi/catkin_ws/src/clever/clever/launch/mavros.launch`. + +## Main services + +`/mavros/set_mode` — set [flight mode](modes.md) of the controller. Usually, the OFFBOARD mode is set \(for control from Raspberry Pi\). + +`/mavros/cmd/arming` — enable or disable drone motors \\ (change the armed status \\). + +## Main published topics + +`/mavros/state` — status of connection to the flight controller. The flight controller mode. + +`/mavros/local_position/pose` — local position of the copter in the ENU system of coordinates, and its orientation. + +`/mavros/local_position/velocity` — current speed in the local coordinates. Angular velocities. + +`/mavros/global_position/global` — the current global position \(latitude, longitude, altitude\). + +`/mavros/global_position/local` — the global position in the [UTM] system of coordinates (https://ru.wikipedia.org/wiki/Система_координат_UTM). + +`/mavros/global_position/rel_alt` — relative altitude \(relative to the engines ON altitude\). + +Messages published in the topics may be viewed by using the `rostopic` utility, e.g., `rostopic echo /mavros/state`. See more in [working with ROS](ros.md). + +## Main topics for publication + +`/mavros/setpoint_position/local` — set the target position and the yaw of the drone \(in the ENU system of coordinates\). + +`/mavros/setpoint_position/cmd_vel` — set the target linear velocity of the drone. + +`/mavros/setpoint_attitude/attitude` and `/mavros/setpoint_attitude/att_throttle` — set target attitude and throttle level. + +`/mavros/setpoint_attitude/cmd_vel` and `/mavros/setpoint_attitude/att_throttle` — set target angular velocity and throttle level. + +### Topics for sending raw packets + +`/mavros/setpoint_raw/local` — sending packet [SET\_POSITION\_TARGET\_LOCAL\_NED](https://pixhawk.ethz.ch/mavlink/#SET_POSITION_TARGET_LOCAL_NED). Allows setting target position/target speed and target yaw/angular yaw velocity. The values to be set are selected using the `type_mask` field. + +`/mavros/setpoint_raw/attitude` — sending packet [SET\_ATTITUDE\_TARGET](https://pixhawk.ethz.ch/mavlink/#SET_ATTITUDE_TARGET). Allows setting the target attitude /angular velocity and throttle level. The values to be set are selected using the `type_mask` field + +`/mavros/setpoint_raw/global` — sending packet [SET\_POSITION\_TARGET\_GLOBAL\_INT](https://pixhawk.ethz.ch/mavlink/#SET_POSITION_TARGET_GLOBAL_INT). Allows setting the target attitude in global coordinates \(latitude, longitude, altitude\) and flight speed. **Not supported in PX4** \([issue](https://github.com/PX4/Firmware/issues/7552)\). \ No newline at end of file diff --git a/docs/en/network.md b/docs/en/network.md new file mode 100644 index 00000000..fca3c7fe --- /dev/null +++ b/docs/en/network.md @@ -0,0 +1,319 @@ +# Configuring Wi-Fi + +The Raspberry Pi Wi-Fi adapter of has two main operating modes: + +1. **Client mode** – RPi connects to an existing Wi-Fi network. +2. **Access point mode** – RPi creates a Wi-Fi network that you can connect to. + +When using [the RPi image](microsd_images.md), the Wi-Fi adapter works in the [access point mode] by default (Wi-Fi.md). + +## Changing the password or SSID (of the network name) + +1. Edit file `/etc/wpa_supplicant/wpa_supplicant.conf` (using [SSH connection](ssh.md)): + + ```bash + sudo nano /etc/wpa_supplicant/wpa_supplicant.conf + ``` + + To change the name of the Wi-Fi network, change the value of parameter `ssid`, to change the password, change parameter `psk`. For example: + + ```txt + network={ + ssid="my-super-ssid" + psk="cleverwifi123" + mode=2 + proto=RSN + key_mgmt=WPA-PSK + pairwise=CCMP + group=CCMP + auth_alg=OPEN + } + ``` + +2. Restart Raspberry Pi. + +> **Caution** The length of the password for the Wi-Fi network should be **at least** 8 characters. +> +> In case of incorrect settings `wpa_supplicant.conf`, Raspberry Pi will stop distributing Wi-Fi! + +## Switching adapter to the client mode + +1. Disable the `dnsmasq` service. + + ```bash + sudo systemctl stop dnsmasq + sudo systemctl disable dnsmasq + ``` + +2. Enable obtaining IP address on the wireless interface by the DHCP client. + + For this purpose, remove the following lines + + ```conf + interface wlan0 + static ip_address=192.168.11.1/24 + ``` + + from file `/etc/dhcpcd.conf` manually, or run the following commands. + + ```bash + sudo sed -i 's/interface wlan0//' /etc/dhcpcd.conf + sudo sed -i 's/static ip_address=192.168.11.1\/24//' /etc/dhcpcd.conf + ``` + +3. Configure `wpa_supplicant` to connect to an existing access point. + + ```bash + cat << EOF | sudo tee /etc/wpa_supplicant/wpa_supplicant.conf + ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev + update_config=1 + country=GB + + network={ + ssid="CLEVER" + psk="cleverwifi" + } + + EOF + ``` + + where `CLEVER` is the name of the network, and `cleverwifi` is the password. + +4. Restart the `dhcpcd` service. + + ```bash + sudo systemctl restart dhcpcd + ``` + +## Switching the adapter to the access point mode + +1. Enable the static IP address in the wireless interface. + + For this purpose, add the following lines + + ```conf + interface wlan0 + static ip_address=192.168.11.1/24 + ``` + + to file `/etc/dhcpcd.conf` manually, or run the following command. + + ```bash + cat << EOF | sudo tee -a /etc/dhcpcd.conf + interface wlan0 + static ip_address=192.168.11.1/24 + + EOF + ``` + +2. Configure wpa_supplicant to work in the access point mode. + + ```bash + cat << EOF | sudo tee /etc/wpa_supplicant/wpa_supplicant.conf + ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev + update_config=1 + country=GB + + network={ + ssid="CLEVER-$(head -c 100 /dev/urandom | xxd -ps -c 100 | sed -e 's/[^0-9]//g' | cut -c 1-4)" + psk="cleverwifi" + mode=2 + proto=RSN + key_mgmt=WPA-PSK + pairwise=CCMP + group=CCMP + auth_alg=OPEN + } + + EOF + ``` + +3. Restart the `dhcpcd` service. + + ```bash + sudo systemctl restart dhcpcd + ``` + +4. Enable the `dnsmasq` service. + + ```bash + sudo systemctl enable dnsmasq + sudo systemctl start dnsmasq + ``` + +___ + +Below you can read more about how RPi networking is organized. + +## RPi network organization + +Network operation in image **2017-11-29-raspbian-stretch-lite** is supported by two pre-installed services: + +* **networking** — the service enables all network interfaces at the moment of start [5]. +* **dhcpcd** — the service ensures configuration of addressing and routing on the interfaces obtained dynamically, or specified statically in the config file. + +To work in the router (access point) mode, RPi requires a DHCP server. It is used to automatically send the settings of the current network to connected clients. `isc-dhcp-server` or `dnsmasq` may be used as such server. + +### dhcpcd + +Starting with Raspbian Jessy, network settings are no longer defined in the `/etc/network/interfaces` file. Now `dhcpcd` is used for sending addressing and routing settings[4]. + +By default, a dhcp client is enabled in all interfaces. Settings of the interfaces are changed in the `/etc/dhcpcd.conf` file. To start an access point, specify a static IP address. To do this, add the following lines to the end of the file: + +``` +interface wlan0 +static ip_address=192.168.11.1/24 +``` + +> **Note** If the interface is wireless (wlan), the `dhcpcd` service triggers `wpa_supplicant` [13], which in turn works directly with the Wi-Fi adapter, and sets it to the specified state. + +### wpa_supplicant + +**wpa_supplicant** — the service configures the Wi-Fi adapter. The `wpa_supplicant` service runs not as standalone (although it exists as such), and runs as a `dhcpcd` child process. + +By default, the config file should contain path `/etc/wpa_supplicant/wpa_supplicant.conf`. +An example of the configuration file: + +```conf +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +country=GB + +network={ + ssid=\"CLEVER-SMIRNOV\" + psk=\"cleverwifi\" + mode=2 + proto=RSN + key_mgmt=WPA-PSK + pairwise=CCMP + group=CCMP + auth_alg=OPEN +} +``` + +Inside the config file, general `wpa_supplicant` settings, and the settings for the adapter configuration are specified. The configuration file also contains `network` section with the basic settings of the Wi-Fi network, such as network SSID, password, adapter operating mode. There may be several such sections, but only the first one is the working one. For example, if the first section contains connection to an unavailable network, the adapter will be configured according to a next valid section, if there is one. Read more about the syntax of `wpa_supplicant.conf` [TODO WIKI]. + +#### wpa_passphrase + +`wpa_passphrase` — a utility for creating the `network` section. + + ```bash +wpa_passphrase SSID PASSWORD +``` + +After running the command, copy the resulting section to your config file. You may remove the commented field `psk`, and leave only the field with the password hash, or vice versa. + +```bash +network={ + ssid="SSID" + #psk="PASSWORD" + psk=c2161655c6ba444d8df94cbbf4e9c5c4c61fc37702b9c66ed37aee1545a5a333 +} +``` + +### Multiple Wi-Fi adapters + +The system may use multiple Wi-Fi adapters. If drivers are properly connected to them, they may be viewed by calling `ifconfig` (e.g. `wlan0` and `wlan1`). + +If you have multiple adapters, the same working `network` section will be used for all of them. This is due to the fact that for each interface, `dhcpcd` separately creates a child `wpa_supplicant` process, which runs the same code ( since the config is the same). + +To make multiple adapters work with individual settings, the mechanism for running different configuration scripts is implemented in the called standard `dhcpcd` script. To use it, rename the standard config file as follows: `wpa_supplicant-.conf`, for example `wpa_supplicant-wlan0.conf`. + +To apply the settings, restart the parent process — the `dhcpcd` service. This can be done by running the following command: + +```bash +sudo systemctl restart dhcpcd +``` + +### DHCP server + +#### dnsmasq-base + +`dnsmasq-base` — a command-line utility, which is not a service. To use dnsmasq as a service, install the `dnsmasq` package. + +```bash +sudo apt install dnsmasq-base +``` + +```bash +# Calling dnsmasq-base +sudo dnsmasq --interface=wlan0 --address=/clever/coex/192.168.11.1 --no-daemon --dhcp-range=192.168.11.100,192.168.11.200,12h --no-hosts --filterwin2k --bogus-priv --domain-needed --quiet-dhcp6 --log-queries + +# More about dnsmasq-base +dnsmasq --help + +# or +man dnsmasq +``` + +#### dnsmasq + +```bash +sudo apt install dnsmasq +``` + +```bash +cat << EOF | sudo tee -a /etc/dnsmasq.conf +interface=wlan0 +address=/clever/coex/192.168.11.1 +dhcp-range=192.168.11.100,192.168.11.200,12h +no-hosts +filterwin2k +bogus-priv +domain-needed +quiet-dhcp6 + +EOF +``` + +#### isc-dhcp-server + +```bash +sudo apt install isc-dhcp-server +``` + +```bash +# https://www.shellhacks.com/ru/sed-find-replace-string-in-file/ +sed -i 's/INTERFACESv4=\"\"/INTERFACESv4=\"wlan0\"/' /etc/default/isc-dhcp-server +``` + +```bash +cat << EOF | sudo tee /etc/dhcp/dhcpd.conf +subnet 192.168.11.0 netmask 255.255.255.0 { + range 192.168.11.11 192.168.11.254; + #option domain-name-servers 8.8.8.8; + #option domain-name "rpi.local"; + option routers 192.168.11.1; + option broadcast-address 192.168.11.255; + default-lease-time 600; + max-lease-time 7200; +} + +EOF +``` + +```bash +cat << EOF | sudo tee /etc/network/if-up.d/isc-dhcp-server && sudo chmod +x /etc/network/if-up.d/isc-dhcp-server +#!/bin/sh +if [ "\$IFACE" = "--all" ]; +then sleep 10 && systemctl start isc-dhcp-server.service & +fi + +EOF +``` + +## Links + +1. [habr.com Linux WiFi from the command line with wpa_supplicant](https://habr.com/post/315960/) +2. [wiki.archlinux.org WPA supplicant (Russian)](https://wiki.archlinux.org/index.php/WPA_supplicant_%28%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9%29) +3. [blog.hoxnox.com: WiFi access point with wpa_supplicant](http://blog.hoxnox.com/gentoo/wifi-hotspot.html) +4. [dmitrysnotes.ru: Raspberry Pi 3. Assigning a static IP addresses](http://dmitrysnotes.ru/raspberry-pi-3-prisvoenie-staticheskogo-ip-adresa) +5. [thegeekdiary.com: Linux OS Service ‘network’](https://www.thegeekdiary.com/linux-os-service-network/) +6. [frillip.com: Using your new Raspberry Pi 3 as a Wi-Fi access point with hostapt](https://frillip.com/using-your-raspberry-pi-3-as-a-wifi-access-point-with-hostapd/) (it also contains instructions for setting up forwarding for using RPi as an Internet gateway) +7. [habr.com: Configuring a ddns server on a GNU/Linux Debian 6](https://habr.com/sandbox/30433/) (Good article on configuring a ddns server based on `bind` and `isc-dhcp-server`) +8. [pro-gram.ru to: Setting up and configuring a DHCP server in Ubuntu 16.04.](https://pro-gram.ru/dhcp-server-ubuntu.html) (setup isc-dhcp-server) +9. [expert-orda.ru: Configuring a DHCP server in Ubuntu](http://expert-orda.ru/posts/liuxnewbie/125--dhcp-ubuntu) (setup isc-dhcp-server) +10. [academicfox.com: A Raspberry Pi wireless access point (WiFi access point)](http://academicfox.com/raspberry-pi-besprovodnaya-tochka-dostupa-wifi-access-point/) (setting the routes, hostapd, isc-dhcp-server) +11. [weworkweplay.com: Automatically connect a Raspberry Pi to a Wifi network](http://weworkweplay.com/play/automatically-connect-a-raspberry-pi-to-a-wifi-network/) (Contains settings for creating an open access point) +12. [wiki.archlinux.org: WPA supplicant](https://wiki.archlinux.org/index.php/WPA%20supplicant) +13. [wiki.archlinux.org: dhcpcd](https://wiki.archlinux.org/index.php/Dhcpcd#10-wpa_supplicant) (dhcpcd hook wpa_supplicant) \ No newline at end of file diff --git a/docs/en/rc.md b/docs/en/rc.md new file mode 100644 index 00000000..d51f6767 --- /dev/null +++ b/docs/en/rc.md @@ -0,0 +1,56 @@ +Controlling Clever from a smartphone +=== + + + +To control Clever from a smartphone via Wi-Fi, you have to install the appropriate application – [iOS](https://itunes.apple.com/ru/app/clever-rc/id1396166572?mt=8), Android (https://play.google.com/store/apps/details?id=express.copter.cleverrc). + +![CLEVER RC](../assets/IMG_4397.PNG) + +> **Warning** The mobile transmitter is mainly intended for indoor flights to the range not exceeding 10-15 m. Many Wi-Fi networks may also impair responsiveness and the range of the transmitter. + +Control from a smartphone is also [available in the mobile version of the app](https://docs.qgroundcontrol.com/en/SettingsView/VirtualJoystick.html) QGroundControl. + +Configuring +--- + +> **Warning** An open QGroundControl or rviz connection sends large amounts of data over Wi-Fi, which can adversely affect responsiveness of the mobile transmitter. It is recommended not to use these applications together with it. + +Install [Clever image on RPi](microsd_images.md). For running the application, settings `rosbridge` and `rc` in the launch file (`~/catkin_ws/src/clever/clever/launch/clever.launch`) should be enabled: + +```xml + +``` + +```xml + +``` + +After the launch-file is edited, restart package `clever`: + +```(bash) +sudo systemctl restart clever +``` + +Also make sure that PX4-parameter `COM_RC_IN_MODE` is set to `0` (RC Transmitter). + +Additional PX4 parameters: + +* `COM_RC_LOSS_T` – timeout for detecting signal loss by the transmitter (mobile or physical). It is recommended to increase the timeout to several seconds. +* `NAV_RCL_ACT` – action upon loss of transmitter signal. + +> **Note** The mobile transmitter conflicts with the real radio control equipment. When the mobile transmitter is used, it should be powered off. + +Connection +--- + +Connect the smartphone to Clever [Wi-Fi](Wi-Fi.md) network (`CLEVER-xxxx`). The application should connect to the copter automatically. Upon successful connection, the current [mode](modes.md) and the battery charge level should be displayed. + +The sticks on the screen of the application work just like real sticks. To arm the copter, hold the left stick in the bottom right corner for several seconds. To disarm — in the bottom left corner. + +Malfunctions +--- + +* If the interface of the transmitter displays a surely incorrect voltage (e.g., > 5 V), check that the value of PX4 parameter `BAT_N_CELLS` matches the actual number of battery cells. If the displayed voltage is still incorrect, calibrate the battery (TODO: link). + +* If instead of mode PX4, text "DISCONNECTED FROM FCU" is displayed, check [Raspberry Pi connection to Pixhawk](connection.md). \ No newline at end of file diff --git a/docs/en/ros.md b/docs/en/ros.md new file mode 100644 index 00000000..2cbef930 --- /dev/null +++ b/docs/en/ros.md @@ -0,0 +1,106 @@ +ROS +=== + +Main article: http://wiki.ros.org + +ROS is a widely used framework for developing complex and distributed robotic systems. + +Installation +--- + +Main article: http://wiki.ros.org/kinetic/Installation/Ubuntu + +ROS is already installed on [the RPi image](microsd_images.md). + +To use ROS on a PC, we recommend using Ubuntu Linux (or a virtual machine such as Parallels Desktop Lite](https://itunes.apple.com/ru/app/parallels-desktop-lite/id1085114709?mt=12) or [VirtualBox](https://www.virtualbox.org)). + +Concepts +--- + +### Nodes + +Main article: http://wiki.ros.org/Nodes + +ROS node is a special program (usually written in Python or C++) that communicates with other nodes via ROS topics and ROS services. Dividing complex robotic systems into isolated nodes provides certain advantages: reduced coupling of the code, increases re-usability and reliability. + +Many robotic libraries, and the driver are executed in the form of ROS-nodes. + +In order to turn an ordinary program into a ROS node, connect to it a `rospy` or `roscpp` library, and add the initialization code. + +An example of a ROS node in Python: + +```python +import rospy + +rospy.init_node('my_ros_node') # the name of the ROS node + +rospy.spin() # entering an endless cycle... +``` + +### Topics + +Main article: http://wiki.ros.org/Topics + +A topic is a named data bus used by the nodes for exchanging messages. Any node can *post* a message in a random topic, and *subscribe* to an arbitrary topic. + +An example of posting a message of type [`std_msgs/String`](http://docs.ros.org/api/std_msgs/html/msg/String.html) (line) in topic `/foo` in Python: + +```python +from std_msgs.msg import String + +# ... + +foo_pub = rospy.Publisher('/foo', String, queue_size=1) # creating a Publisher +foo_pub.publish(data='Hello, world!') # posting the message +``` + +An example of subscription to topic `/foo`: + +```python +def foo_callback(msg): + print msg.data + +# Subscribing. When a message is received in topic /foo, function foo_callback will be invoked. +rospy.Subscriber('/foo', String, foo_callback) +``` + +There is also an opportunity to work with the topics using the `rostopic` utility. For example, using the following command, one can view messages published in topic `/variety of the Aegean sea/state`: + +```(bash) +rostopic echo /mavros/state +``` + +### Services + +Main article: http://wiki.ros.org/Services + +A service is an analogue to the function that can be called from one node, and processed in another one. The service has a name that is similar to the name of the topic, and 2 message types: request type and response type. + +An example of invoking a ROS service from Python: + +```python +from clever.srv import GetTelemetry + +# ... + +# Creating a wrapper for the get_telemetry service of the clever package with the GetTelemetry type: +get_telemetry = rospy.ServiceProxy('get_telemetry', srv.GetTelemetry) + +# Invoking the service, and receiving the quadcopter telemetry: +telemetry = get_telemetry() +``` + +You can also work with the services using the `rosservice` utility. For instance, you can call service `/get_telemetry` from the command line: + +```(bash) +rosservice call /get_telemetry "{frame_id: ''}" +``` + +More examples of using the services for Clever quadcopter autonomous flights are available in the [documentation for node simple_offboard](simple_offboard.md). + +Working on several PCs +--- + +Main article: http://wiki.ros.org/ROS/Tutorials/MultipleMachines. + +The advantage of using ROS is the possibility of distributing the nodes across several PCs in the network. For example, a node that recognizes an image may be run on a more powerful PC; the node that controls the copter may be run directly on a Raspberry Pi connected to the flight controller, etc. \ No newline at end of file diff --git a/docs/en/simple_offboard.md b/docs/en/simple_offboard.md new file mode 100644 index 00000000..c72035aa --- /dev/null +++ b/docs/en/simple_offboard.md @@ -0,0 +1,321 @@ +Simple offboard +=== + +> **Note** Documentation for the [image](microsd_images.md), versions, starting with **0.15**. For older versions refer to [documentation for version **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/simple_offboard.md). + +The `simple_offboard` module of the `clever` package is intended for simplified programming of an autonomous drone ([mode](modes.md) `OFFBOARD`). It allows setting the desired flight tasks, and automatically transforms [the system of coordinates](frames.md). + +`simple_offboard` is a high level way of interacting with the flight controller. For a more low level work, see [mavros](mavros.md). + +Main services are `get_telemetry` (receiving all telemetry), `navigate` (flying to a given point along a straight line), `navigate_global` (flying to a global point along a straight line), `land` (switching to the landing mode). + +The use of Python language +--- + +To use the services, create proxies to them. An example of the program the declared proxies to all `simple_offboard` services: + +```python +import rospy +from clever import srv +from std_srvs.srv import Trigger + +rospy.init_node('flight') # flight – name of your ROS node + +# Creating proxies to all services: + +get_telemetry = rospy.ServiceProxy('get_telemetry', srv.GetTelemetry) +navigate = rospy.ServiceProxy('navigate', srv.Navigate) +navigate_global = rospy.ServiceProxy('navigate_global', srv.NavigateGlobal) +set_position = rospy.ServiceProxy('set_position', srv.SetPosition) +set_velocity = rospy.ServiceProxy('set_velocity', srv.SetVelocity) +set_attitude = rospy.ServiceProxy('set_attitude', srv.SetAttitude) +set_rates = rospy.ServiceProxy('set_rates', srv.SetRates) +land = rospy.ServiceProxy('land', Trigger) +release = rospy.ServiceProxy('release', Trigger) +``` + +Unused proxy functions may be removed from the code. + +API description +--- + +> **Note** Blank numeric parameters are set to 0. + +### get_telemetry + +Obtaining complete telemetry of the copter. + +Parameters: + +* `frame_id` – [frame](frames.md) for values `x`, `y`, `z`, `vx`, `vy`, `vz`. Example: `map`, `body`, `aruco_map`. Default value: `map`. + +Response format: + +* `frame_id` — frame; +* `connected` – whether there is a connection to FCU; +* `armed` `armed` state of propellers (the propellers are armed, if true); +* `mode` – current [flight mode](modes.md); +* `x, y, z` — local position of the copter *(m)*; +* `lat, lon` – latitude, longitude *(degrees)*, [GPS] is to be available (gps.md); +* `alt` – altitude in the global system of coordinates (standard [WGS-84](https://ru.wikipedia.org/wiki/WGS_84), not AMSL!), [GPS] is to be available (gps.md); +* `vx, vy, vz` – copter velocity *(m/s)*; +* `pitch` – pitch angle *(radians)*; +* `roll` – roll angle *(radians)*; +* `yaw` — yaw angle *(radians)*; +* `pitch_rate` — angular pitch velocity *(rad/s)*; +* `roll_rate` – angular roll velocity *(rad/s)*; +* `yaw_rate` – angular yaw velocity *(rad/s)*; +* `voltage` – total battery voltage *(V)*; +* `cell_voltage` – battery cell voltage *(V)*. + +> **Note** Fields that are available for some reason will contain the `NaN` value. + +Displaying copter coordinates `x`, `y` and `z` in the local system of coordinates: + +```python +telemetry = get_telemetry() +print telemetry.x, telemetry.y, telemetry.z +``` + +Displaying copter altitude relative to [the card of ArUco tags](aruco.md): + +```python +telemetry = get_telemetry(frame_id='aruco_map') +print telemetry.z +``` + +Checking global position availability: + +```python +import math +if not math.isnan(get_telemetry().lat): + print 'Global position presents' +else: + print 'No global position' +``` + +Output of current telemetry (command line): + +```(bash) +rosservice call /get_telemetry "{frame_id: ''}" +``` + +### navigate + +Fly to the designated point in a straight line. + +Parameters: + +* `x`, `y` — coordinates *(m)*; +* `yaw` — yaw angle *(radians)*; +* `yaw_rate` – angular yaw velocity (used for setting the yaw to `NaN`) *(rad/s)*; +* `speed` – flight speed (setpoint speed) *(m/s)*; +* `auto_arm` – switch the copter to `OFFBOARD` and arm automatically (**the copter will take off**); +* `frame_id` – [system of coordinates](frames.md) for values `x`, `y`, `z`, `vx`, `vy`, `vz`. Example: `map`, `body`, `aruco_map`. Default value: `map`. + +> **Note** To fly without changing the yaw angle, it is sufficient to set the `yaw` to `NaN` (angular velocity by default is 0). + +Ascending to the altitude of 1.5 m with the climb rate of 0.5 m/s: + +```python +navigate(x=0, y=0, z=1.5, speed=0.5, frame_id='body', auto_arm=True) +``` + +Flying in a straight line to point 5:0 (altitude 2) in the local system of coordinates at the speed of 0.8 m/s (yaw is set to 0): + +```python +navigate(x=5, y=0, z=3, speed=0.8) +``` + +Flying to point 5:0 without changing the yaw angle (`yaw` = `NaN`, `yaw_rate` = 0): + +```python +navigate(x=5, y=0, z=3, speed=0.8, yaw=float('nan')) +``` + +Flying 3 m to the right from the copter: + +```python +navigate(x=0, y=-3, z=0, speed=1, frame_id='body') +``` + +Turn 90 degrees counterclockwise: + +```python +navigate(yaw=math.radians(-90), frame_id='body') +``` + +Flying to point 3:2 (altitude 2) in the system of coordinates [of the marker field](aruco.md) at the speed of 1 m/s: + +```python +navigate(x=3, y=2, z=2, speed=1, frame_id='aruco_map') +``` + +Rotating on the spot at the speed of 0.5 rad/s (counterclockwise): + +```python +navigate(x=0, y=0, z=0, yaw=float('nan'), yaw_rate=0.5, frame_id='body') +``` + +Flying 3 meters forwards at the speed of 0.5 m/s, yaw-rotating at the speed of 0.2 rad/s: + +```python +navigate(x=3, y=0, z=0, speed=0.5, yaw=float('nan'), yaw_rate=0.2, frame_id='body') +``` + +Ascending to the altitude of 2 m (command line): + +```(bash) +rosservice call /navigate "{x: 0.0, y: 0.0, z: 2, yaw: 0.0, yaw_rate: 0.0, speed: 0.5, frame_id: 'body', auto_arm: true}" +``` + +### navigate_global + +Flying in a straight line to a point in the global system of coordinates (latitude/longitude). + +Parameters: + +* `lat`, `lon` — latitude and longitude *(degrees)*; +* `z` — altitude *(m)*; +* `yaw` — yaw angle *(radians)*; +* `yaw_rate` – angular yaw velocity (used for setting the yaw to `NaN`) *(rad/s)*; +* `speed` – flight speed (setpoint speed) *(m/s)*; +* `auto_arm` – switch the copter to `OFFBOARD` and arm automatically (**the copter will take off**); +* `frame_id` – [system of coordinates](frames.md), given `z` и `yaw` (Default value: `map`). + +> **Note** To fly without changing the yaw angle, it is sufficient to set the `yaw` to `NaN` (angular velocity by default is 0). + +Flying to a global point at the speed of 5 m/s, while remaining at current altitude (`yaw` will be set to 0, the copter will face East): + +```python +navigate_global(lat=55.707033, lon=37.725010, z=0, speed=5, frame_id='body') +``` + +Flying to a global point without changing the yaw angle (`yaw` = `NaN`, `yaw_rate` = 0): + +```python +navigate_global(lat=55.707033, lon=37.725010, z=0, speed=5, yaw=float('nan'), frame_id='body') +``` + +Flying to a global point (command line): + +```(bash) +rosservice call /navigate_global "{lat: 55.707033, lon: 37.725010, z: 0.0, yaw: 0.0, yaw_rate: 0.0, speed: 5.0, frame_id: 'body', auto_arm: false}" +``` + +### set_position + +Set the target by position and yaw. This service may be used to specify the continuous flow of target points, for example, for flying along complex trajectories (circular, arcuate, etc.). + +> **Hint** For flying to a point in a straight line or takeoff, use the [`navigate`] higher-level service (#navigate). + +Parameters: + +* `x`, `y`, `z` — point coordinates *(m)*; +* `yaw` — yaw angle *(radians)*; +* `yaw_rate` – angular yaw velocity (used for setting the yaw to NaN) *(rad/s)*; +* `auto_arm` – switch the copter to `OFFBOARD` and arm automatically (**the copter will take off**); +* `frame_id` – [system of coordinates](frames.md), given `x`, `y`, `z` и `yaw` (Default value: `map`). + +Hovering on the spot: + +```python +set_position(frame_id='body') +``` + +Assigning the target point 3 m above the current position: + +```python +set_position(x=0, y=0, z=3, frame_id='body') +``` + +Assigning the target point 1 m ahead of the current position: + +```python +set_position(x=1, y=0, z=0, frame_id='body') +``` + +Rotating on the spot at the speed of 0.5 rad/s: + +```python +set_position(x=0, y=0, z=0, frame_id='body', yaw=float('nan'), yaw_rate=0.5) +``` + +### set_velocity + +Setting speed and yaw. + +* `vx`, `vy`, `vz` – required flight speed *(m/s)*; +* `yaw` — yaw angle *(radians)*; +* `yaw_rate` – angular yaw velocity (used for setting the yaw to NaN) *(rad/s)*; +* `auto_arm` – switch the copter to `OFFBOARD` and arm automatically (**the copter will take off**); +* `frame_id` – [system of coordinates](frames.md), given `vx`, `vy`, `vz` и `yaw` (Default value: `map`). + +> **Note** Parameter `frame_id` specifies only the orientation of the resulting velocity vector, but not its length. + +Flying forward (relative to the copter) at the speed of 1 m/s: + +```python +set_velocity(vx=1, vy=0.0, vz=0, frame_id='body') +``` + +One of variants of flying in a circle: + +```python +set_velocity(vx=0.4, vy=0.0, vz=0, yaw=float('nan'), yaw_rate=0.4, frame_id='body') +``` + +### set_attitude + +Setting pitch, roll, yaw and throttle level (approximate analogue to control in [the `STABILIZED` mode](modes.md)). This service may be used for lower level monitoring of the copter behavior or controlling the copter, if no reliable data about its position are available. + + +Parameters: + +* `pitch`, `roll`, `yaw` – required pitch, roll, and yaw angle *(radians)*; +* `thrust` — throttle level from 0 (no throttle, propellers are stopped) to 1 (full throttle). +* `auto_arm` – switch the copter to `OFFBOARD` and arm automatically (**the copter will take off**); +* `frame_id` – [system of coordinates](frames.md), given `yaw` (Default value: `map`). + +### set_rates + +Setting pitch, roll, and yaw angular velocity and the throttle level (approximate analogue to control in [the `ACRO` mode](modes.md)). This is the lowest copter control level (excluding direct control of motor rotation speed). This service may be used to automatically perform acrobatic tricks (e.g., flips). + +Parameters: + +* `pitch_rate`, `roll_rate`, `yaw_rate` – angular pitch, roll, and yaw velocity *(rad/s)*; +* `thrust` — throttle level from 0 (no throttle, propellers are stopped) to 1 (full throttle). +* `auto_arm` – switch the copter to `OFFBOARD` and arm automatically (**the copter will take off**); + +### land + +Transfer the copter to the landing [mode](modes.md) (`AUTO.LAND` or similar). + +> **Note** For automated disabling the propellers after landing [parameter PX4](px4_parameters.md) `COM_DISARM_LAND` is to be set to a value > 0. + +Landing the copter: + +```python +res = land() + +if res.success: + print 'Copter is landing' +``` + +Landing the copter (command line): + +```(bash) +rosservice call /land "{}" +``` + + + +Additional materials +------------------------ + +* [Flying in the field of ArUco markers](aruco.md). +* [Samples of programs and snippets](snippets.md). \ No newline at end of file diff --git a/docs/en/web_video_server.md b/docs/en/web_video_server.md new file mode 100644 index 00000000..11e582f1 --- /dev/null +++ b/docs/en/web_video_server.md @@ -0,0 +1,57 @@ +# Viewing images from cameras + +To view images from cameras (or other Ros topics), you can use [rviz](rviz.md), rqt, or watch them in a browser using web\_video\_server. + +See read more about [using rqt](rviz.md). + +## Viewing in a browser + +### Configuration + +Make sure that in Clever launch-file \(`~/catkin_ws/src/clever/clever/launch/clever.launch`\), starting `web_video_server` is enabled: + +```xml + +``` + +After the launch-file is edited, restart package `clever`: + +```bash +sudo systemctl restart clever +``` + +### Viewing + +To view a video-stream, you have to [connect to Wi-Fi](Wi-Fi.md) of Clever \(`CLEVER-xxxx`\), navigate to page [http://192.168.11.1:8080/](http://192.168.11.1:8080/), and choose the topic. + +![Viewing web_video_server](../assets/web_video_server.png) + +If the image is transmitted too slow, you can speed it up by changing GET parameter `quality` (from 1 to 100), which is responsible for video-stream compression, for example: + +http://192.168.11.1:8080/stream_viewer?topic=/main_camera/image_raw&quality=1 + +At the URL above, a stream from the main camera will be available in the minimum possible quality. + +Parameters `width`, `height`, etc. re also available. Read more about `web_video_server`: http://wiki.ros.org/web_video_server. + +## Browse with rqt_image_view + +To browse images with the rqt tools the user needs a computer with Ubuntu 16.04 и [ROS Kinetic](http://wiki.ros.org/kinetic/Installation/Ubuntu). + +[Connect to the Clever Wi-Fi network](wifi.md) an run `rqt_image_view` with its IP-address: + +```bash +ROS_MASTER_URI=http://192.168.11.1:11311 rqt_image_view +``` + +Choose a topic for browsing, for example `/main_camera/image_raw`: + +![rqt_image_view](../assets/rqt_image_view.jpg) + +To reduce network load and reduce latency, use a compressed version of the topic – `/main_camera/image_raw/compressed`. + +To change the compression settings use the rqt-plugin Dynamic Reconfigure: + +![rqt_image_view+rqt_dynamic_reconfigure](../assets/rqt_image_view_dyn_rec.jpg) + +Refer to [more about rviz and rqt](rviz.md). \ No newline at end of file From 232401e73069c1929a05a8a4277b5dc92e73f2a7 Mon Sep 17 00:00:00 2001 From: Konstantin Eliseev <1deaglea@gmail.com> Date: Tue, 5 Feb 2019 14:20:11 +0300 Subject: [PATCH 2/3] EN articles update 8 new English articles --- docs/en/SUMMARY.md | 15 +-- docs/en/aruco.md | 171 ++++++++++++++++++++++++++ docs/en/camera.md | 110 +++++++++++++++++ docs/en/camera_frame.md | 63 ++++++++++ docs/en/leds.md | 233 ++++++++++++++++++++++++++++++++++++ docs/en/rviz.md | 75 ++++++++++++ docs/en/selfcheck.md | 32 +++++ docs/en/snippets.md | 259 ++++++++++++++++++++++++++++++++++++++++ docs/en/sonar.md | 133 +++++++++++++++++++++ 9 files changed, 1084 insertions(+), 7 deletions(-) create mode 100644 docs/en/aruco.md create mode 100644 docs/en/camera.md create mode 100644 docs/en/camera_frame.md create mode 100644 docs/en/leds.md create mode 100644 docs/en/rviz.md create mode 100644 docs/en/selfcheck.md create mode 100644 docs/en/snippets.md create mode 100644 docs/en/sonar.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index d95ab2c7..ffd1f4ee 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -30,10 +30,11 @@ * [ROS](ros.md) * [MAVROS](mavros.md) * [Simple offboard](simple_offboard.md) - - - - - - - +* [Navigation using ArUco markers](aruco.md) +* [Automatic check](selfcheck.md) +* [Code examples](snippets.md) +* [Adjusting the position of the main camera](camera_frame.md) +* [Working with the camera](camera.md) +* [Working with a LED strip on Raspberry 3](leds.md) +* [Using rviz and rqt](rviz.md) +* [Working with the ultrasonic distance gage](sonar.md) diff --git a/docs/en/aruco.md b/docs/en/aruco.md new file mode 100644 index 00000000..881ee40d --- /dev/null +++ b/docs/en/aruco.md @@ -0,0 +1,171 @@ +# Navigation using ArUco markers + +> **Note** Documentation for the versions [of image](microsd_images.md), starting with **0.15**. For earlier versions, see [documentation for version **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/aruco.md). + +[ArUco-Markers] (https://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html) is a popular technology for positioning +robotic systems using computer vision. + +Examples of ArUco markers: + +![ArUco markers](../assets/markers.jpg) + +> **Hint** Use the most matte paper for printing visual markers. Glossy paper may glitter in the light, severely deteriorating the quality of recognition. + +For rapid generation of markers for printing, you may use an online tool: http://chev.me/arucogen/. + +## aruco\_pose + +The `aruco_pose` module allows restoring the position of the copter relative to the map of ArUco markers and communicating it to the flight controller using the [Vision Position Estimation] mechanism (https://dev.px4.io/en/ros/external_position_estimation.html). + +If the source of the copter position by the markers is available, the option appears for precise autonomous indoor navigation by the positions using the [simple\_offboard] module (simple_offboard.md). + +### Turning on + +Make sure that in the clever launch file \(`~/catkin_ws/src/clever/clever/launch/clever.launch`\), the start of aruco\_pose and [computer vision cameras] is turned on(camera.md): + +```xml + +``` + +```xml + +``` + +After the launch-file is edited, restart package `clever`: + +```(bash) +sudo systemctl restart clever +``` + +### Calibrating the ArUco marker map. + +An automatically generated [ArUco-board] may be used as a map of marks (https://docs.opencv.org/trunk/db/da9/tutorial_aruco_board_detection.html). + +The map of marks is adjusted using file `~/catkin_ws/src/clever/clever/launch/aruco.launch`. To use ArUco-board, enter its parameters: + +```xml + + + + + + + + + + + + + + + + + + + + +``` + +The vertical and horizontal distance between the markers may be set separately: + +```xml + + + + + +``` + +If a map with a custom order of marker IDs is used, parameter `marker_ids` may be used: + +```xml +[5, 7, 9, 11, 13, 15] +``` + +The markers are numbered from the top left corner of the field. + +For monitoring the map that is currently used by the copter for navigation, one can watch the content of topic `aruco_pose/map_image`. In a browser, it may be viewed with [web\_video\_server](web_video_server.md) by following the link [http://192.168.11.1:8080/snapshot?topic=/aruco\_pose/map\_image](http://192.168.11.1:8080/snapshot?topic=/aruco_pose/map_image): + +![](../../assets/Снимок экрана 2017-11-27 в 23.20.49.png) + +When flying, make sure that the markers glued to the floor correspond to the map. + +In topic `aruco_pose/debug` \([http://192.168.11.1:8080/snapshot?topic=/aruco\_pose/debug](http://192.168.11.1:8080/snapshot?topic=/aruco_pose/debug)\) the current result of markers recognitions is available: + +TODO + +### The system of coordinates + +According to [agreement](http://www.ros.org/reps/rep-0103.html), the standard ENU system of coordinates is used in the marker field: + +* x — rightward \(conditional East\); +* y — forward \(conditional North\); +* z — upward. + +_Note_: the definition above is provided for a situation when the marker field is on the floor. + +First, the zero is the bottom left point of the marker field. The yaw angle is considered zero when the copter is faced rightward\(along the x-axis\). + +![The system of markers coordinates](../assets/aruco-frame.png) + +### Configuring the flight controller + +Correct Vision Position Estimation requires making sure \(via [QGroundControl](gcs_bridge.md)\) that: + +* **For Pixhawk**: Firmware with LPE \(local position estimator\) is installed. For Pixhawk [download firmware `px4fmu-v2_lpe.px4`](https://github.com/PX4/Firmware/releases). + + **For Pixracer**: parameter `SYS_MC_EST_GROUP` should be set to`local_position_estimator, attitude_estimator_q`. + + > **Note** After changing the value of parameter `SYS_MC_EST_GROUP` restart the flight controller. +* In parameter `LPE_FUSION` **only** flags `vision position`, `land detector` are enabled. The final value _20_. +* Compass disabled: `ATT_W_MAG` = 0 +* Complimentary filter external heading weight: `ATT_W_EXT_HDG` = 0.5 +* Orientation by yaw by vision enabled: `ATT_EXT_HDG_M` = 2 `MOCAP`. +* VPE settings: `LPE_VIS_DELAY` = 0 sec, `LPE_VIS_XY` = 0.1 m, `LPE_VIS_Z` = 0.15 m. +* Recommended settings for land detector: + * `COM_DISARM_LAND` = 1 s + * `LNDMC_ROT_MAX` = 45 deg + * `LNDMC_THR_RANGE` = 0.5 + * `LNDMC_Z_VEL_MAX` = 1 m/s + + + +### Flight + +A properly configured copter starts holding position by VPE \(in [modes](modes.md) `POSCTL` or `OFFBOARD`\) automatically. + +For [autonomous flights](simple_offboard.md) do you will be able to use functions `navigate`, `set_position`, `set_velocity`. For flying to specific coordinates of the marker field, use frame `aruco_map`: + +```python +# First, the copter has to take off to see the map of marks +# and for frame aruco_map to appear: +navigate(0, 0, 2, frame_id='body', speed=0.5, auto_arm=True) # take off to the altitude of 2 meters + +time.sleep(5) + +# Flying to coordinate 2:2 of the marker field at the altitude of 2 meters +navigate(2, 2, 2, speed=1, frame_id='aruco_map') # flying to coordinate 2:2 at the altitude of 3 meters +``` + +See [other functions](simple_offboard.md) simple_offboard. + +### Location of markers on the ceiling + +![Markers on the ceiling](../assets/IMG_4175.JPG) + +To navigate by the markers placed on the ceiling, you need to set the main camera facing up and [set the corresponding frame of the camera](camera_frame.md). + +To set the map of markers in a "turned over" system of coordinates, change parameter `aruco_orientation` in file `~/catkin_ws/src/clever/clever/aruco.launch`: + +```xml + +``` + +When this parameter is set, frame aruco\_map will also be "turned over". Thus, to fly at the altitude of 2 meters below the ceiling, argument `z` should be set to 2: + +```python +navigate(x=1, y=2, z=1.1, speed=0.5, frame_id='aruco_map') \ No newline at end of file diff --git a/docs/en/camera.md b/docs/en/camera.md new file mode 100644 index 00000000..db940742 --- /dev/null +++ b/docs/en/camera.md @@ -0,0 +1,110 @@ +# Working with the camera + +To work with the main camera, make sure it is enabled in file `~/catkin_ws/src/clever/clever/launch/clever.launch`: + +```xml + +``` + +Also make sure that [correct position and orientation are indicated] for the camera (camera_frame.md). + +The `clever` package must be restarted after the launch-file has been edited: + +```(bash) +sudo systemctl restart clever +``` + +For monitoring images from the camera, you may use rqt or [web_video_server](web_video_server.md). + +## Computer vision + +For implementation of the computer vision algorithms, it is recommended to use the [OpenCV] library that is pre-installed in [the SD card image] (microsd_images.md) (https://opencv.org). + +### Python + +Main article: http://wiki.ros.org/cv_bridge/Tutorials/ConvertingBetweenROSImagesAndOpenCVImagesPython. + +An example of creating a subscriber for a topic with an image from the main camera for processing with OpenCV: + +```python +import rospy +import cv2 +from sensor_msgs.msg import Image +from cv_bridge import CvBridge + +rospy.init_node('computer_vision_sample') +bridge = CvBridge() + +def image_callback(data): + cv_image = bridge.imgmsg_to_cv2(data, 'bgr8') # OpenCV image + # Do any image processing with cv2... + +image_sub = rospy.Subscriber('main_camera/image_raw', Image, image_callback) + +rospy.spin() +``` + +To debug image processing, you can publish a separate topic with the processed image: + +```python +image_pub = rospy.Publisher('~debug', Image) +``` + +Publishing the processed image (at the end of the image_callback function): + +```python +image_pub.publish(bridge.cv2_to_imgmsg(cv_image, 'bgr8')) +``` + +The obtained images can be viewed using [web_video_server](web_video_server.md). + +### Examples + +#### Working with QR codes + +> **Hint** For high-speed recognition and positioning, it is better to use [ArUco markers] (aruco.md). + +To program actions of the copter upon detection of [QR codes] (https://ru.wikipedia.org/wiki/QR-код) you can use the [ZBar] library (http://zbar.sourceforge.net). It should be installed using pip: + +```(bash) +sudo pip install zbar +``` + +Recognizing QR codes in Python: + +```python +import cv2 +import zbar +from cv_bridge import CvBridge +from sensor_msgs.msg import Image + +bridge = CvBridge() +scanner = zbar.ImageScanner() +scanner.parse_config('enable') + +# Image subscriber callback function +def image_callback(data): + cv_image = bridge.imgmsg_to_cv2(data, 'bgr8') # OpenCV image + gray = cv2.cvtColor(cv_image, cv2.COLOR_BGR2GRAY, dstCn=0) + + pil = ImageZ.fromarray(gray) + raw = pil.tobytes() + + image = zbar.Image(320, 240, 'Y800', raw) # Image params + scanner.scan(image) + + for symbol in image: + # print detected QR code + print 'decoded', symbol.type, 'symbol', '"%s"' % symbol.data + +image_sub = rospy.Subscriber('main_camera/image_raw', Image, image_callback, queue_size=1) +``` + +The script will take up to 100% CPU capacity. To slow down the script artificially, you can run [throttling](http://wiki.ros.org/topic_tools/throttle) of frames from the camera, for example, at 5 Hz (`main_camera.launch`): + +```xml + +``` + +The topic for the subscriber in this case should be changed for `main_camera/image_raw/throttled`. \ No newline at end of file diff --git a/docs/en/camera_frame.md b/docs/en/camera_frame.md new file mode 100644 index 00000000..1f1227e6 --- /dev/null +++ b/docs/en/camera_frame.md @@ -0,0 +1,63 @@ +# Adjusting the position of the main camera + +> **Note** Documentation for the versions [of image](microsd_images.md), starting with **0.15**. For earlier versions, see [documentation for version **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/camera_frame.md). + +Position and orientation of the main camera is determined in file `~/catkin_ws/src/clever/clever/launch/main_camera.launch`: + +```xml + +``` + +This line sets static transformation between frame `base_link` ([corresponds to the flight controller housing](frames.md)) and the camera (`main_camera_optical`) in format: + +```txt +shift_x shift_y shift_z yaw_angle pitch_angle roll_angle +``` + +The frame of the camera is set so that: + +* **x** points to the right in the picture; +* **y** points down in the picture; +* **z** points away from the camera matrix plane. + +Shifts are set in meters, angles — in radians. Correctness of the transformation set may be checked using [rviz](rviz.md). + +## Settings for Clever + +The first image — how a copter model looks in rviz with these settings, the second image — how Clever looks with the same settings. + +### 1. The camera is facing downward, the flat cable — backward + +```xml + +``` + + + + +### 2. The camera is facing downwards, the flat cable — forward + +```xml + +``` + + + + +### 3. The camera is facing upward, the flat cable — backward + +```xml + +``` + + + + +### 4. The camera is facing upward, the flat cable — forward + +```xml + +``` + + + \ No newline at end of file diff --git a/docs/en/leds.md b/docs/en/leds.md new file mode 100644 index 00000000..79a3c7c5 --- /dev/null +++ b/docs/en/leds.md @@ -0,0 +1,233 @@ +# Working with a LED strip on Raspberry 3 + +## Connecting and determining the type of the strip + +There are two main types of addressed LEDs: WS2812B and WS2812. The control principle is the same, but the timings are different. Locate a LED chip on the strip, and determine how many pins it has: 6 or 4. If it has 6 pins, it is WS2812; if 4, it is WS2812B or its analog SK6812. + +leds + +Since the control principle is the same, the strips are connected the same way: + +| strip | Raspberry Pi | +| :---: | :---: | +| GND | GND | +| 5V | 5V | +| DIN | GPIO21 or GPIO31 | + +strip types for denoting the strip in the code are described in [file](https://github.com/jgarff/rpi_ws281x/blob/master/ws2811.h). The main strip types are WS2812\_STRIP \(for WS2812\) and SK6812\_STRIP \(for WS2812B or SK6812\). + +## Installing a library for working with the LED strip + +Define the folder that will contain files of the library, and open the path to this folder in the terminal. By default, you can use the home folder, to move to it, run command: + +```(bash) +cd ~ +``` + +Clone the repository of library for working with LED strips on Raspberry Pi: + +```(bash) +git clone https://github.com/jgarff/rpi_ws281x.git +``` + +Install [Scons](https://ru.wikipedia.org/wiki/SCons) and [Swig](https://ru.wikipedia.org/wiki/SWIG): + +```(bash) +sudo apt-get install scons python-dev swig +``` + +Compile the library using Scons \(the command is to be run inside the folder with the source code of the library\): + +```(bash) +cd rpi_ws281x +scons +``` + +Compile the Python wrapper for the library using Swig, and set it for using in your Python scripts. + +```(bash) +cd python +sudo python ./setup.py build +sudo python ./setup.py install +``` + +## Sample program for a LED bang on RPI3 + +In a text editor, open file `strandtest.py` from folder `python/examples` \(located in the folder with the library\): + +```(bash) +nano strandtest.py +``` + +Locate the part of the code with strip settings: + +```(bash) +# LED strip configuration: +LED_COUNT = 16 # Number of LED pixels. +LED_PIN = 18 # GPIO pin connected to the pixels (18 uses PWM!). +#LED_PIN = 10 # GPIO pin connected to the pixels (10 uses SPI /dev/spidev0.0). +LED_FREQ_HZ = 800000 # LED signal frequency in hertz (usually 800khz) +LED_DMA = 10 # DMA channel to use for generating signal (try 10) +LED_BRIGHTNESS = 255 # Set to 0 for darkest and 255 for brightest +LED_INVERT = False # True to invert the signal (when using NPN transistor level shift) +LED_CHANNEL = 0 # set to '1' for GPIOs 13, 19, 41, 45 or 53 +LED_STRIP = ws.WS2811_STRIP_GRB # Strip type and color ordering +``` + +Adjust the settings for working with the strip, and save the file. To avoid interference of the use of the strip with the operation of other devices on Raspberry Pi, it is recommended to use the following settings \(the settings are for a strip together with Clever 3\): + +```(bash) +# LED strip configuration: +LED_COUNT = 30 # Number of LED pixels. +LED_PIN = 21 # GPIO pin connected to the pixels. +LED_FREQ_HZ = 800000 # LED signal frequency in hertz (usually 800khz) +LED_DMA = 10 # DMA channel to use for generating signal (try 10) +LED_BRIGHTNESS = 255 # Set to 0 for darkest and 255 for brightest +LED_INVERT = False # True to invert the signal (when using NPN transistor level shift) +LED_CHANNEL = 0 # set to '1' for GPIOs 13, 19, 41, 45 or 53 +LED_STRIP = ws.SK6812_STRIP # Strip type and color ordering +``` + +Run the test program from root: + +```(bash) +sudo python strandtest.py +``` + +The root privileges are required for executing the script, since without them there is no access to the interrupt functions used by the library to work with the strip. + +## Compatibility with ROS and Python + +When the program is run using sudo, the user environment changes, and errors of library import appear, since required paths are missing in the environment. To add paths to Python libraries and ROS packages to the environment, add the following lines to file `/etc/sudoers` : + +```(bash) +Defaults env_keep += "PYTHONPATH" +Defaults env_keep += "PATH" +Defaults env_keep += "ROS_ROOT" +Defaults env_keep += "ROS_MASTER_URI" +Defaults env_keep += "ROS_PACKAGE_PATH" +Defaults env_keep += "ROS_LOCATIONS" +Defaults env_keep += "ROS_HOME" +Defaults env_keep += "ROS_LOG_DIR" +``` + +## Functions for working with the LED strip + +To connect the library and its correct operation, engage the following modules: neopixel - for strip operation, time – for delay management, and sys and signal for interruptions and forming the control signal. + +```python +from neopixel import * +import time +import signal +import sys +``` + +To work with the strip, create an object of type **Adafruit_NeoPixel**, and initialize the library: + +```python +# Creating a NeoPixel object with specifies configuration +strip = Adafruit_NeoPixel(LED_COUNT, LED_PIN, LED_FREQ_HZ, LED_DMA, LED_INVERT) +# Initialization of the library, to be run before other functions +strip.begin() +``` + +The main functions that are used to control the strip: + +* `numPixels()` - returns the number of pixels in the strip. It is convenient for cyclical control of the entire strip. +* `setPixelColor(pos, color)` – sets pixel color to position `pos`, to color `color`. The color should be a 24 bit value, where the first 8 bits are red color \(red\), the next 8 bits — green \(green\), and the last 8 bits — blue \(blue\). To get the `color` value, you can use function `Color(red, green, blue)`, which composes this value of 3 components. Each component should be in the range 0 – 255, where 0 is no color, and 255 — the highest brightness of the component available in the LED module. +* `setPixelColorRGB(pos, red, green, blue)` – sets the pixel color at position pos to the color that consists of components `red`, `green`, `blue`. Each component should be in the range 0 – 255, where 0 is no color, and 255 — the highest brightness of the component available in the LED module. +* `show()` – updates the state of the strip. It is only after using it that all software changes are moved to the LED strip. + +Other functions may be detected by running command + +```(bash) +pydoc neopixel +``` + +The result of the command: + +```(bash) + Help on module neopixel: + + NAME + neopixel + + DESCRIPTION + # Adafruit NeoPixel library port to the rpi_ws281x library. + # Author: Tony DiCola (tony@tonydicola.com) + + CLASSES + __builtin__.object + Adafruit_NeoPixel + + class Adafruit_NeoPixel(__builtin__.object) + | Methods defined here: + | + | __del__(self) + | + | __init__(self, num, pin, freq_hz=800000, dma=5, invert=False) + | Class to represent a NeoPixel/WS281x LED display. Num should be the + | number of pixels in the display, and pin should be the GPIO pin connected + | to the display signal line (must be a PWM pin like 18!). Optional + | parameters are freq, the frequency of the display signal in hertz (default + | 800khz), dma, the DMA channel to use (default 5), and invert, a boolean + | specifying if the signal line should be inverted (default False). + | + | begin(self) + | Initialize library, must be called once before other functions are + | called. + | + | getPixelColor(self, n) + | Get the 24-bit RGB color value for the LED at position n. + | + | getPixels(self) + | Return an object which allows access to the LED display data as if + | it were a sequence of 24-bit RGB values. + | + | numPixels(self) + | Return the number of pixels in the display. + | + | setBrightness(self, brightness) + | Scale each LED in the buffer by the provided brightness. The brightness + | of 0 is the darkest and 255 is the brightest. Note that scaling can have + | quantization issues (i.e. blowing out to white or black) if used repeatedly! + | + | setPixelColor(self, n, color) + | Set LED at position n to the provided 24-bit color value (in RGB order). + | + | setPixelColorRGB(self, n, red, green, blue) + | Set LED at position n to the provided red, green, and blue color. + | Each color component should be a value from 0 to 255 (where 0 is the + | lowest intensity and 255 is the highest intensity). + | + | show(self) + | Update the display with the data from the LED buffer. + | + + FUNCTIONS + Color(red, green, blue) + Convert the provided red, green, blue color to a 24-bit color value. + Each color component should be a value 0-255 where 0 is the lowest intensity + and 255 is the highest intensity. +``` + +## Why exactly so, and is there a different way? + +The main types of strips used for Clever 3 are WS2812, WS2812B and SK6812 \(analog to WS2812B\). They are controlled according to the same principle: for a massif of LEDs in the strip, a data packet at the rate of 24 bits per LED; each led reads the first 24 bits of received data, and sets the corresponding color, the rest of the data are sent to the next LED in the strip. Zeros and ones are determined by different combinations of the durations of high and low level in the pulse. + +All these strips are supported for library management [rpi_ws281x](https://github.com/jgarff/rpi_ws281x), with that, the DMA module\(direct memory access \) of the Raspberri processor, and one of the data channels re used for control: PWM, PCM, or SPI, which guarantees absence of delays in control \(and everything is controlled from a multitasking OS, it's important\). + +There are some peculiarities of working with channels, for example, when transmitting data using PWM \\ (PWM \\), the built-in audio system stops working, when transmitting data via PCM, the use of connected digital audio devices is blocked\\ (with that, the built-in system keeps working \\), and when using SPI \(by the way, special adjustment of buffer size and Raspberry GPU frequency is required for proper operation\) the LED strip blocks all other devices connected to that channel. + +There are some peculiarities of DMA channel selection to control the strip: some channels are used by the system, so using them may lead to unpleasant consequences; for example, using channel 5 destroys the Raspberry file system, since this channel is used for reading / writing to the SD card. Secure channel is No. 10, it is set by default in the library above. + +Therefore, the scenarios of using the LED strip are the following: + +1. If performance of embedded audio on Raspberry is not important \(and we don't use it, since the audio and the strip will produce nonsense in this case\), it is possible to use the PWM channel \(for this purpose, you have to connect strip inputs to one of the following Raspberry GPIO ports: 12, 18, 40, or 52 for PWM0 channel and 13, 19, 41, 45, or 53 for PWM1 channel\). +2. If presence of other devices on the SPI bus is not important, you can control the strip via the SPI \(GPIO on Raspberry 10 or 38\) channel. + Here the following settings are required \(only for Raspberry Pi 3\): + * increase the size of the data transfer buffer to support long strips, by adding line `spidev.bufsiz=32768` to file `/boot/cmdline.txt`; + * set the GPU frequency for proper the frequency of SPI, by adding line `core_freq=250` to file `/boot/config.txt`. +3. If both audio operation and connection of SPI devices in addition to the LED strip is important, the strip may be controlled via the PCM channel \(GPIO 21 or 31\). With that, no further manipulations with Raspberry is required. + +Based on the above methods of controlling the strip, the best variant that allows controlling the strip, preserve operability of the built-in audio system, and the possibility of connecting all sorts of devices and sensors via the SPI is the controlling via the PCM \(GPIO 21\) channel using the 10 DMA channel. diff --git a/docs/en/rviz.md b/docs/en/rviz.md new file mode 100644 index 00000000..a94e8b7d --- /dev/null +++ b/docs/en/rviz.md @@ -0,0 +1,75 @@ +Using rviz and rqt +=== + +![rviz](../assets/rviz.png) + +The [rviz] tool(http://wiki.ros.org/rviz) allows real-time visualization of all components of the robotic system —the system of coordinates, moving parts, sensors, camera images — on the 3D stage. + +[rqt](http://wiki.ros.org/rqt) is a set of GUI for analyzing and controlling ROS systems. For example, `rqt_image_view` allows viewing topics with images, `rqt_multiplot` allows plot charts by the values in topics, etc. + +To use rviz and rqt, a PC running Ubuntu Linux (or a virtual machine such as [Parallels Desktop Lite] (https://itunes.apple.com/ru/app/parallels-desktop-lite/id1085114709?mt=12) or [VirtualBox] (https://www.virtualbox.org)) is required. + +Install package `ros-kinetic-desktop-full` or `ros-kinetic-desktop` using the [installation documentation](http://wiki.ros.org/kinetic/Installation/Ubuntu). + +Start rviz +--- + +To start еру visualization of the state of Clever in real time, connect to it via Wi-Fi (`CLEVER-xxx`) and run rviz, specifying an appropriate ROS_MASTER_URI: + +```(bash) +ROS_MASTER_URI=http://192.168.11.1:11311 rviz +``` + +If connection is not established, make sure the `.bashrc` of Clever contains line: + +```(bash) +export ROS_IP=192.168.11.1 +``` + +Using rviz +--- + +### Visualization of the copter position + +It is recommended to set the `map` frame as a reference frame. To visualize the copter, add visualization markers from topic `/vehicle_markers`. To visualize the camera of the copter, add visualization markers from topic `/main_camera/camera_markers`. + +The result of copter and camera visualization is shown below: + +![rviz](../assets/copter_visualization.png) + +### Visualization of the environment + +You can view a picture with augmented reality from the topic of the main camera `/main_camera/image_raw`. + +Axis or Grid configured to frame `aruco_map` will visualize the location [on the map of ArUco marks](aruco.md). + +### jsk_rviz_plugins + +It is also recommended to install additional useful plugins for rviz [jsk_rviz_plugins](https://jsk-docs.readthedocs.io/en/latest/jsk_visualization/doc/jsk_rviz_plugins/index.html). This kit allows visualizing topics like `TwistStamped` (velocity) `CameraInfo`, `PolygonArray`, and many more. To install, use command: + +```(bash) +sudo apt-get install ros-kinetic-jsk-visualization +``` + +Starting the rqt toolkit +--- + +![rqt](../assets/rqt.png) + +To start rqt for monitoring Clever status, use command: + +```(bash) +ROS_MASTER_URI=http://192.168.11.1:11311 rqt +``` + +An example of starting a specific plugin (`rqt_image_view`): + +```(bash) +ROS_MASTER_URI=http://192.168.11.1:11311 rqt_image_view +``` + +Brief description of useful rqt plugins: + +* `rqt_image_view` – viewing images from topics like `sensor_msgs/Image`; +* `rqt_multiplot` – Building charts from the data from of arbitrary topics (installation: `sudo apt-get install ros-kinetic-rqt-multiplot`); +* Bag – working with [Bag-files](http://wiki.ros.org/rosbag). \ No newline at end of file diff --git a/docs/en/selfcheck.md b/docs/en/selfcheck.md new file mode 100644 index 00000000..8445e083 --- /dev/null +++ b/docs/en/selfcheck.md @@ -0,0 +1,32 @@ +# Automatic check + +Before flying (especially autonomous), you can use several methods of automatic self-testing of the quadcopter subsystems. + +## selfcheck.py + +Utility `selfcheck.py` is part of `clever` package, and automatically tests the main aspects of the ROS platform and the PX4. The utility is pre-installed on [the Raspberry Pi image](microsd_images.md). + +To initiate it, type in [the Raspberry Pi console](ssh.md): + +```(bash) +rosrun clever selfcheck.py +``` + + + +Description of some checks: + +* FCU – checking proper connection with the flight controller; +* IMU – checking correctness of the data from IMU; +* Local position – presence of the local position of the drone; +* Velocity estimation – drone velocity estimation (**if this check fails, never take off offline!**); +* Global position (GPS) — presence of the global position (GPS required); +* Camera — proper operation of the Raspberry camera. + +## commander check + +To check the main sub systems of PX4 and the possibility of arming at the moment, you can perform command `commander check` in the MAVLink console. + + + +When using SITL instead of the MAVLink console, use a terminal with SITL running. \ No newline at end of file diff --git a/docs/en/snippets.md b/docs/en/snippets.md new file mode 100644 index 00000000..ad281ebe --- /dev/null +++ b/docs/en/snippets.md @@ -0,0 +1,259 @@ +Code examples +=== + +Python +--- + +> **Note** If Cyrillic characters in the UTF-8 charset are used, specify the charset at the beginning of the program: +> ```python +> # -*- coding: utf-8 -*- +> ``` + +### # {#distance} + +The function of determining the distance between two points (**important**: the points are to be in the same [system of coordinates](frames.md)): + +```python +def get_distance(x1, y1, z1, x2, y2, z2): + return math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2 + (z1 - z2) ** 2) +``` + +### # {#distance-global} + +A function for approximate determination of the distance (in meters) between two global coordinates (latitude/longitude): + +```python +def get_distance_global(lat1, lon1, lat2, lon2): + return math.hypot(lat1 - lat2, lon1 - lon2) * 1.113195e5 +``` + +### # {#block-takeoff} + +Takeoff and waiting for the end of takeoff: + +```python +z = 2 # altitude +tolerance = 0.2 # precision of altitude check (m) + +# Remembering the initial point +start = get_telemetry() + +# Take off to the altitude of 2 m +print navigate(z=z, speed=0.5, frame_id='body', auto_arm=True) + +# Waiting for takeoff +while True: + # Checking current altitude + if get_telemetry().z - start.z + z < tolerance: + # Takeoff complete + break + rospy.sleep(0.2) +``` + +### # {#block-nav} + +Flying to a point and waiting for the copter to arrive at it: + +```python +tolerance = 0.2 # precision of arrival check (m) +frame_id='aruco_map' + +# Flying to point 1:2:3 in the field of ArUco markers +print navigate(frame_id=frame_id, x=1, y=2, z=3, speed=0.5) + +# Wait for the copter to arrive at the requested point +while True: + telem = get_telemetry(frame_id=frame_id) + # Calculating the distance to the requested point + if get_distance(1, 2, 3, telem.x, telem.y, telem.z) < tolerance: + # Arrived at the requested point + break + rospy.sleep(0.2) +``` + +### # {#disarm} + +Quadcopter disarm (disabling propellers **the copter will fall down**): + +```python +# Declaring a proxy: +from mavros_msgs.srv import CommandBool +arming = rospy.ServiceProxy('mavros/cmd/arming', CommandBool) + +# ... + +arming(False) # дизарм +``` + +### # {#transform} + +Transforming the position (`PoseStamped`) from one system of coordinates ([of frame](frames.md)) to another one using [tf2] (http://wiki.ros.org/tf2): + +```python +import tf2_ros +import tf2_geometry_msgs + +tf_buffer = tf2_ros.Buffer() +tf_listener = tf2_ros.TransformListener(tf_buffer) + +# ... + +# Creating as PoseStamped object (or getting it from the topic): +pose = PoseStamped() +pose.header.frame_id = 'map' # frame, which is the position is specified +pose.header.stamp = rospy.get_rostime() # the moment for which the position is specified (current time) +pose.pose.position.x = 1 +pose.pose.position.y = 2 +pose.pose.position.z = 3 +pose.pose.orientation.w = 1 + +frame_id = 'base_link' # target frame +transform_timeout = rospy.Duration(0.2) # wait for transformation timeout + +# Transforming the position from the old frame to the new one: +new_pose = tf_buffer.transform(pose, frame_id, transform_timeout) +``` + +### # {#upside-down} + +Determining whether the copter is turned over: + +```python +PI_2 = math.pi / 2 +telem = get_telemetry() + +flipped = not -PI_2 <= telem.pitch <= PI_2 or not -PI_2 <= telem.roll <= PI_2 +``` + +### # {#angle-hor} + +Calculating the copter total angle to the horizon: + +```python +PI_2 = math.pi / 2 +telem = get_telemetry() + +flipped = not -PI_2 <= telem.pitch <= PI_2 or not -PI_2 <= telem.roll <= PI_2 +angle_to_horizon = math.atan(math.hypot(math.tan(telem.pitch), math.tan(telem.roll))) +if flipped: + angle_to_horizon = math.pi - angle_to_horizon +``` + +### # {#circle} + +Flying along a circular path: + +```python +RADIUS = 0.6 # m +SPEED = 0.3 # rad / s + +start = get_telemetry() +start_stamp = rospy.get_rostime() + +r = rospy.Rate(10) + +while not rospy.is_shutdown(): + angle = (rospy.get_rostime() - start_stamp).to_sec() * SPEED + x = start.x + math.sin(angle) * RADIUS + y = start.y + math.cos(angle) * RADIUS + set_position(x=x, y=y, z=start.z) + + r.sleep() +``` + +### # {#rate} + +repeating an action with the frequency of 10 Hz: + +```python +r = rospy.Rate(10) +while not rospy.is_shutdown(): + # Do anything + r.sleep() +``` + +### # {#mavros-sub} + +An example of subscription to a topic from MAVROS + +```python +from geometry_msgs.msg import PoseStamped, TwistStamped +from sensor_msgs.msg import BatteryState +from mavros_msgs.msg import RCIn + +# ... + +def state_update(pose): + # Processing new data about the copter position + pass + +# Other handler functions +# ... + +rospy.Subscriber('/mavros/local_position/pose', PoseStamped, pose_update) +rospy.Subscriber('/mavros/local_position/velocity', TwistStamped, velocity_update) +rospy.Subscriber('/mavros/battery', BatteryState, battery_update) +rospy.Subscriber('mavros/rc/in', RCIn, rc_callback) +``` + +Information about MAVROS topics us available at [the link](mavros.md). + + + +### # {#mavlink} + + + +An example of sending an arbitrary [MAVLink message](mavlink.md) to the copter: + +```python +# ... + +from mavros_msgs.msg import Mavlink +from mavros import mavlink +from pymavlink import mavutil + +# ... + +mavlink_pub = rospy.Publisher('mavlink/to', Mavlink, queue_size=1) + +# Sending a HEARTBEAT message: + +msg = mavutil.mavlink.MAVLink_heartbeat_message(mavutil.mavlink.MAV_TYPE_GCS, 0, 0, 0, 0, 0) +msg.pack(mavutil.mavlink.MAVLink('', 2, 1)) +ros_msg = mavlink.convert_to_rosmsg(msg) + +mavlink_pub.publish(ros_msg) +``` + +### # {#rc-sub} + +Reaction to switching the mode on the transmitter (may be used for starting an offline flight, see [example](https://gist.github.com/okalachev/b709f04522d2f9af97e835baedeb806b)): + +```python +from mavros_msgs.msg import RCIn + +# Called when new data are received from the transmitter +def rc_callback(data): + # Arbitrary reaction to switching the toggle switch on the transmitter + if data.channels[5] < 1100: + # ... + pass + elif data.channels[5] > 1900: + # ... + pass + else: + # ... + pass + +# Creating a subscriber for the topic with the data from the transmitter +rospy.Subscriber('mavros/rc/in', RCIn, rc_callback) + +rospy.spin() +``` + +### # {#flip} + +Flip: + +TODO \ No newline at end of file diff --git a/docs/en/sonar.md b/docs/en/sonar.md new file mode 100644 index 00000000..1b21b2dc --- /dev/null +++ b/docs/en/sonar.md @@ -0,0 +1,133 @@ +# Working with the ultrasonic distance gage + +Ultrasonic distance gage (*"sonar"*) is a distance gage based on the principle of measuring the time of a sound wave (about 40 kHz) propagation to the obstacle and back. The sonar can measure the distance up to 1.5 – 3 m with the accuracy of several centimeters. + +## Distance gage HC-SR04 + +hc-sr04 + +## Installation + +The distance gage is attached to the body using double-sided tape. For obtaining acceptable results, the use of vibro-insulation is required. A piece of PU foam may be used for vibro-insulation. + +### Connection + +Connect HC-SR04 to Raspberry Pi according to the connection diagram. Use 1.0 and 2.2 kΩ resistors and any free GPIO pins, e.g., 23 and 24: + +Connecting HC-SR04 + +> **Hint** Instead of a 2.2 kΩ resistor, you can use two 1 kΩ resistors connected in series. + + + +> **Hint** There are several interchangeable pins **GND** and **VCC 5V** on Raspberry Pi. Use the [pinout] (https://pinout.xyz) to find them. + +### Reading the data + +To read the data from distance gage HC-SR04 library for working with GPIO is used – [`pigpio`](http://abyz.me.uk/rpi/pigpio/index.html). This library is pre-installed in the [Clever image](microsd_images.md), starting with version **v0.14**. For older versions of the image, use [an installation guide](http://abyz.me.uk/rpi/pigpio/download.html). + +To work with `pigpio`, start appropriate daemon: + +```(bash) +sudo systemctl start pigpiod.service +``` + +You can also enable `pigpiod` auto launch on system startup: + +```(bash) +sudo systemctl enable pigpiod.service +``` + +Thus, it becomes possible to interact with the `pigpiod` daemon from Python: + +```python +import pigpio +pi = pigpio.pi() +``` + +> **Hint** See detailed description of Python API in [`pigpio` documentation](http://abyz.me.uk/rpi/pigpio/python.html). + +An example of the code for reading data from HC-SR04: + +```python +import time +import threading +import pigpio + +TRIG = 23 is the No. of the pin connected to the Trig contact of the distance gage +TRIG = 24 is the No. of the pin connected to the Echo contact of the distance gage + +pi = pigpio.pi() +done = threading.Event() + +def rise(gpio, level, tick): + global high + high = tick + +def fall(gpio, level, tick): + global low + low = tick - high + done.set() + +def read_distance(): + done.clear() + pi.gpio_trigger(TRIG, 50, 1) + done.wait(timeout=5) + return low / 58.0 / 100.0 + +pi.set_mode(TRIG, pigpio.OUTPUT) +pi.set_mode(ECHO, pigpio.INPUT) +pi.callback(ECHO, pigpio.RISING_EDGE, rise) +pi.callback(ECHO, pigpio.FALLING_EDGE, fall) + +while True: + # Reading the distance: + print read_distance() + +``` + +### Filtering the data + +To filter (smooth out) the data and delete [emission](https://ru.wikipedia.org/wiki/Outbreak_%28statistics%29) [Kalman filter] (https://ru.wikipedia.org/wiki/Фильтр_Калмана) or a simple [median filter](https://ru.wikipedia.org/wiki/Median_filter) can be used. An example of median filtering implementation: + +```python +import collections +import numpy + +# ... + +history = collections.deque(maxlen=10) # 10 - количество сэмплов для усреднения + +def read_distance_filtered(): + history.append(read_distance()) + return numpy.median(history) + +while True: + print read_distance_filtered() +``` + +An example of charts of initial and filtered data: + + + +The source code of the ROS-node used for building the chart can be found [on Gist](https://gist.github.com/okalachev/feb2d7235f5c9636802c3cda43add253). + +## Distance gage RCW-0001 + + + +Ultrasonic distance gage RCW-0001 is compatible with distance gage HC-SR04. Use the instruction above to connect and work with it. + +## Flight + +An example of a flight program with the use of [simple_offboard](simple_offboard.md), which makes the copter fly forward until the connected ultrasonic distance gage detects an obstacle: + +```python +set_velocity(x=0.5, frame_id='body', auto_arm=True) # flying forward at the velocity of 0.5 mps + +while True: + if read_distance_filtered() < 1: + # if the obstacle is closer than 1 m, hanging on the spot + set_position(x=0, y=0, z=0, frame_id='body') + rospy.sleep(0.1) +``` \ No newline at end of file From 5847992d2636bd2be368f64f60ef6c0dc3d5d41c Mon Sep 17 00:00:00 2001 From: Oleg Kalachev Date: Sat, 9 Feb 2019 06:07:59 +0300 Subject: [PATCH 3/3] docs: make linter happy --- docs/en/aruco.md | 4 ++-- docs/en/camera.md | 6 +++--- docs/en/network.md | 3 +-- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/en/aruco.md b/docs/en/aruco.md index 881ee40d..150c4b75 100644 --- a/docs/en/aruco.md +++ b/docs/en/aruco.md @@ -37,7 +37,7 @@ After the launch-file is edited, restart package `clever`: sudo systemctl restart clever ``` -### Calibrating the ArUco marker map. +### Calibrating the ArUco marker map An automatically generated [ArUco-board] may be used as a map of marks (https://docs.opencv.org/trunk/db/da9/tutorial_aruco_board_detection.html). @@ -168,4 +168,4 @@ To set the map of markers in a "turned over" system of coordinates, change param When this parameter is set, frame aruco\_map will also be "turned over". Thus, to fly at the altitude of 2 meters below the ceiling, argument `z` should be set to 2: ```python -navigate(x=1, y=2, z=1.1, speed=0.5, frame_id='aruco_map') \ No newline at end of file +navigate(x=1, y=2, z=1.1, speed=0.5, frame_id='aruco_map') diff --git a/docs/en/camera.md b/docs/en/camera.md index db940742..83af7b62 100644 --- a/docs/en/camera.md +++ b/docs/en/camera.md @@ -62,9 +62,9 @@ The obtained images can be viewed using [web_video_server](web_video_server.md). #### Working with QR codes -> **Hint** For high-speed recognition and positioning, it is better to use [ArUco markers] (aruco.md). +> **Hint** For high-speed recognition and positioning, it is better to use [ArUco markers](aruco.md). -To program actions of the copter upon detection of [QR codes] (https://ru.wikipedia.org/wiki/QR-код) you can use the [ZBar] library (http://zbar.sourceforge.net). It should be installed using pip: +To program actions of the copter upon detection of [QR codes](https://en.wikipedia.org/wiki/QR_code) you can use the [ZBar] library (http://zbar.sourceforge.net). It should be installed using pip: ```(bash) sudo pip install zbar @@ -107,4 +107,4 @@ The script will take up to 100% CPU capacity. To slow down the script artificial args="messages main_camera/image_raw 5.0 main_camera/image_raw/throttled"/> ``` -The topic for the subscriber in this case should be changed for `main_camera/image_raw/throttled`. \ No newline at end of file +The topic for the subscriber in this case should be changed for `main_camera/image_raw/throttled`. diff --git a/docs/en/network.md b/docs/en/network.md index 89a00ffb..21724bfe 100644 --- a/docs/en/network.md +++ b/docs/en/network.md @@ -2,7 +2,6 @@ The Raspberry Pi Wi-Fi adapter of has two main operating modes: - 1. **Client mode** – RPi connects to an existing Wi-Fi network. 2. **Access point mode** – RPi creates a Wi-Fi network that you can connect to. @@ -318,4 +317,4 @@ EOF 10. [academicfox.com: A Raspberry Pi wireless access point (WiFi access point)](http://academicfox.com/raspberry-pi-besprovodnaya-tochka-dostupa-wifi-access-point/) (setting the routes, hostapd, isc-dhcp-server) 11. [weworkweplay.com: Automatically connect a Raspberry Pi to a Wifi network](http://weworkweplay.com/play/automatically-connect-a-raspberry-pi-to-a-wifi-network/) (Contains settings for creating an open access point) 12. [wiki.archlinux.org: WPA supplicant](https://wiki.archlinux.org/index.php/WPA%20supplicant) -13. [wiki.archlinux.org: dhcpcd](https://wiki.archlinux.org/index.php/Dhcpcd#10-wpa_supplicant) (dhcpcd hook wpa_supplicant) \ No newline at end of file +13. [wiki.archlinux.org: dhcpcd](https://wiki.archlinux.org/index.php/Dhcpcd#10-wpa_supplicant) (dhcpcd hook wpa_supplicant)