CopterExpress/clover
1
0
Fork 0
mirror of https://github.com/CopterExpress/clover.git synced 2026-05-26 21:19:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

New EN Articles

Browse Source 
9 new EN articles
This commit is contained in:
Konstantin Eliseev
2019-01-25 18:32:04 +03:00
committed by GitHub
parent 63506698e9
commit dffd818a42
9 changed files with 1015 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/en/SUMMARY.md
View File

@@ -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)
* [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)

16
docs/en/frames.md Normal file
View File

@@ -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).

69
docs/en/gcs_bridge.md Normal file
View File

@@ -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
<arg name="gcs_bridge" default="tcp"/>
```
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
<arg name="gcs_bridge" default="udp-b"/>
```
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
<arg name="gcs_bridge" default="udp-b"/>
```
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
<arg name="gcs_bridge" default="udp-b"/>
```
After opening the QGroundControl application, the connection should be established automatically.

55
docs/en/mavros.md Normal file
View File

@@ -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)\).

319
docs/en/network.md Normal file
View File

@@ -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-<interface name>.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)

56
docs/en/rc.md Normal file
View File

@@ -0,0 +1,56 @@
Controlling Clever from a smartphone
===
<a href="https://itunes.apple.com/ru/app/clever-rc/id1396166572?mt=8"><img src="../assets/appstore.svg"></a><a href="https://play.google.com/store/apps/details?id=express.copter.cleverrc"><img src="../assets/google_play.png" width="15%"></a>
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
<arg name="rosbridge" default="true"/>
```
```xml
<arg name="rc" default="true"/>
```
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).

106
docs/en/ros.md Normal file
View File

@@ -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.

321
docs/en/simple_offboard.md Normal file
View File

@@ -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 <abbr title="Flight Control Unit flight controller">FCU</abbr>;
* `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 <abbr title="Above Mean Sea Level">AMSL</abbr>!), [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 "{}"
```
<!--
### release
Stop publishing setpoints to the copter (release control). Required to continue monitoring by means of [MAVROS](mavros.md).
-->
Additional materials
------------------------
* [Flying in the field of ArUco markers](aruco.md).
* [Samples of programs and snippets](snippets.md).

57
docs/en/web_video_server.md Normal file
View File

@@ -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
<arg name="web_video_server" default="true"/>
```
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).