[Snek] [PATCH] Add documentation for EV3 Servo motors

[Mikhail Gusarov]

---
 doc/snek.adoc              | 43 ++++++++++++++++++++++++++++++++++++++
 ports/ev3/snek-ev3.builtin |  4 ++--
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/doc/snek.adoc b/doc/snek.adoc
index 5c4aeb7..8ed1535 100644
--- a/doc/snek.adoc
+++ b/doc/snek.adoc
@@ -2794,6 +2794,49 @@ Sensor ports are named 1-4, matching the markings on EV3 body.
 Sensors are detected automatically, so they can be plugged/unplugged while Snek
 is running.
 
+The following motors are supported:
+
+* link:https://www.lego.com/en-us/product/ev3-large-servo-motor-45502[Lego EV3 Large Servo Motor]
+* link:https://www.lego.com/en-us/product/ev3-medium-servo-motor-45503[Lego EV3 Medium Servo Motor]
+
+Servo motors have two-way communication with the host, so current speed (either
+from applicaiton of power or from manual rotation) and current position of the
+motor can be queried:
+
+* `read` reads the current speed of the motor (-3 to 3 rotations per second),
+* `position` reads the current position of the motor (rotations from reset).
+
+Servo motors remember the initial position after reset, so the `position` can
+become arbitrarily big.
+
+Current motor to control is selected by using `talkto` with port names
+`'A'` to `'D'`.
+
+The following operations are available on the selected motor:
+
+- `setpower` sets the motor speed, from -3 to 3 rotations per second.
+- `setleft` makes the motor rotate counterclockwise when positive speed is requested.
+- `setright` makes the motor rotate clockwise when positive speed is requested.
+- `on` starts the motor
+- `off` stops the motor
+- `onfor` starts the motor for specified amount of seconds. This function returns
+  immediately.
+- `setposition` starts the motor it running until it reaches the given position
+  (measured in rotations). This function returns immediately.
+- `ramp_up` sets the ramp-up time. The argument specifies duration in seconds
+  from 0 to maximum speed. If a speed smaller than maximum is requested, ramp-up
+  time is shortened proportionally.
+- `ramp_down` sets the ramp-down time in the same manner.
+
+Servo motors have several modes for stopping, select them using the following functions:
+
+- `coast`. Once the desired position is reached, remove the power. The motor
+  coasts to stop. This is the default mode.
+- `brake`. Once the desired position is reached, remove the power and apply
+  passive load on the motor. Motor stops quicker than when coasting.
+- `hold`. Once the desired position is reached, actively hold the position by
+  turning the motor to the desired position.
+
 To run Snek on EV3:
 
 - link:https://www.ev3dev.org/docs/getting-started/[boot ev3dev],
diff --git a/ports/ev3/snek-ev3.builtin b/ports/ev3/snek-ev3.builtin
index c1726fb..dfe50b5 100644
--- a/ports/ev3/snek-ev3.builtin
+++ b/ports/ev3/snek-ev3.builtin
@@ -23,13 +23,13 @@ light_ambient, 1
 light_color, 1
 light_rgb, 1
 
-# sensor values, motor speed in rotations per second, 0..3
+# sensor values, motor speed in rotations per second, -3..3
 read, 1
 
 # select the motor to talk to
 talkto, 1
 
-# set motor speed (power), in rotations per second, 0..3
+# set motor speed (power), in rotations per second, -3..3
 setpower, 1
 
 # motors: direction
-- 
2.24.0