doc: snippets.md

docs/en/snippets.md

@@ -4,9 +4,18 @@ Code examples
 Python
 ---
 
+<!-- markdownlint-disable MD031 -->
+
+> **Note** When using cyrillic simbols with UTF-8 encoding, specify the encoding in the beginning of the program:
+> ```python
+> # -*- coding: utf-8 -*-
+> ```
+
+<!-- markdownlint-enable MD031 -->
+
 ### # {#distance}
 
-The function of determining the distance between two points (**important**: the points are to be in the same [system of coordinates](frames.md)):
+Calculating 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):
@@ -15,7 +24,7 @@ def get_distance(x1, y1, z1, x2, y2, z2):
 
 ### # {#distance-global}
 
-A function for approximate determination of the distance (in meters) between two global coordinates (latitude/longitude):
+Approximation of distance (in meters) between two global coordinates (latitude/longitude):
 
 ```python
 def get_distance_global(lat1, lon1, lat2, lon2):
@@ -24,16 +33,16 @@ def get_distance_global(lat1, lon1, lat2, lon2):
 
 ### # {#block-takeoff}
 
-Takeoff and waiting for the end of takeoff:
+Takeoff and waiting for it to finish:
 
 ```python
 z = 2  # altitude
 tolerance = 0.2 # precision of altitude check (m)
 
-# Remembering the initial point
+# Saving the initial point
 start = get_telemetry()
 
-# Take off to the altitude of 2 m
+# Take off and leveling at 2 m above the ground
 print navigate(z=z, speed=0.5, frame_id='body', auto_arm=True)
 
 # Waiting for takeoff
@@ -47,7 +56,7 @@ while True:
 
 ### # {#block-nav}
 
-Flying to a point and waiting for the copter to arrive at it:
+Flying towards a point and waiting for copter's arrival:
 
 ```python
 tolerance = 0.2 # precision of arrival check (m)
@@ -93,10 +102,10 @@ tf_listener = tf2_ros.TransformListener(tf_buffer)
 
 # ...
 
-# Creating as PoseStamped object (or getting it from the topic):
+# PoseStamped object creation (or getting it from a 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.header.stamp = rospy.get_rostime() # the instant for which the position is specified (current time)
 pose.pose.position.x = 1
 pose.pose.position.y = 2
 pose.pose.position.z = 3
@@ -111,7 +120,7 @@ new_pose = tf_buffer.transform(pose, frame_id, transform_timeout)
 
 ### # {#upside-down}
 
-Determining whether the copter is turned over:
+Determining whether the copter is turned upside-down:
 
 ```python
 PI_2 = math.pi / 2
@@ -122,7 +131,7 @@ 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:
+Calculating the copter total horizontal angle:
 
 ```python
 PI_2 = math.pi / 2
@@ -158,7 +167,7 @@ while not rospy.is_shutdown():
 
 ### # {#rate}
 
-repeating an action with the frequency of 10 Hz:
+repeating an action at a frequency of 10 Hz:
 
 ```python
 r = rospy.Rate(10)
@@ -179,7 +188,7 @@ from mavros_msgs.msg import RCIn
 # ...
 
 def pose_update(pose):
-    # Processing new data about the copter position
+    # Processing new data of copter's position
     pass
 
 # Other handler functions
@@ -191,7 +200,7 @@ 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).
+Information about MAVROS topics is available at [the link](mavros.md).
 
 <!-- markdownlint-disable MD044 -->
 
@@ -199,7 +208,7 @@ Information about MAVROS topics us available at [the link](mavros.md).
 
 <!-- markdownlint-enable MD044 -->
 
-An example of sending an arbitrary [MAVLink message](mavlink.md) to the copter:
+Sending an arbitrary [MAVLink message](mavlink.md) to the copter:
 
 ```python
 # ...
@@ -223,14 +232,14 @@ 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)):
+Return on mode switching with the transmitter (may be used for starting an autonomous 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
+# Called when new data is received from the transmitter
 def rc_callback(data):
-    # Arbitrary reaction to switching the toggle switch on the transmitter
+    # Return on switch toggling of the transmitter
         if data.channels[5] < 1100:
         # ...
         pass
@@ -247,8 +256,53 @@ rospy.Subscriber('mavros/rc/in', RCIn, rc_callback)
 rospy.spin()
 ```
 
+### # {#set_mode}
+
+Change the [flight mode](modes.md) to arbitrary one:
+
+```python
+from mavros_msgs.srv import SetMode
+
+# ...
+
+set_mode = rospy.ServiceProxy('mavros/set_mode', SetMode)
+
+# ...
+
+set_mode(custom_mode='STABILIZED')
+```
+
 ### # {#flip}
 
-Flip:
+Flip on roll:
 
-TODO
+```python
+import math
+
+# ...
+
+def flip():
+    start = get_telemetry()  # saving starting position
+
+    set_rates(thrust=1)  # bump up
+    rospy.sleep(0.2)
+
+    set_rates(roll_rate=30, thrust=0.2)  # maximum roll rate
+
+    while True:
+        telem = get_telemetry()
+
+        if -math.pi + 0.1 < telem.roll < -0.2:
+            break
+
+    rospy.loginfo('finish flip')
+    set_position(x=start.x, y=start.y, z=start.z, yaw=start.yaw)  # finish flip
+
+print navigate(z=2, speed=1, frame_id='body', auto_arm=True)  # take off
+rospy.sleep(10)
+
+rospy.loginfo('flip')
+flip()
+```
+
+Requires the [special PX4 firmware for Clever](firmware.md#прошивка-для-клевера). Before running a flip, take all necessary safty precautions.