Docs: toc everywhere

erdnaxe · Jul 17, 2020 · 64f445a · 64f445a
1 parent a0426fe
commit 64f445a
Show file tree

Hide file tree

Showing 12 changed files with 101 additions and 16 deletions.
diff --git a/docs/build_the_electronics.md b/docs/build_the_electronics.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # PCB
 
 PCB were designed using Eagle 9, which demo version is sufficient.
@@ -11,6 +17,11 @@ PCB design files are available here :
 
 ![Boards](img/boards.png)
 
+!!! Warning "Only one serial port"
+
+    These PCB connect all servomotors serial ports together.
+    This may bottleneck your communication speed later, so if your board have more serial ports you may remix those files.
+
 * * *
 
 ## Battery
@@ -27,10 +38,10 @@ but you may go with a Lithium battery
 that will have a better capacity over mass, thus being more dangerous.
 With the NiMH cells, we measured around 2 hours of autonomy using the robot.
 
-### Battery protection and connection
+!!! Danger "Battery protection and connection"
 
-For the battery, **you should use a fuse** and a switch in series
-and then connect onto the large battery connector of the power board.
+    For the battery, **you should use a fuse** and a switch in series
+    and then connect onto the large battery connector of the power board.
 
 ### Powering the embedded computer
 

diff --git a/docs/build_the_structure.md b/docs/build_the_structure.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Build the structure
 
 This section focuses on building the base structure of the robot.

diff --git a/docs/gym_environments.md b/docs/gym_environments.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Introduction to reinforcement learning
 
 **Reinforcement learning** (RL) consists in using machine learning techniques to

diff --git a/docs/implementations_ppo.md b/docs/implementations_ppo.md
@@ -1,8 +1,10 @@
-# Learning algorithm
+**Table of content**:
 
 [TOC]
 
-## Choosing a learning algorithm
+* * *
+
+# Choosing a learning algorithm
 
 This project choose to use **Proximal Policy Optimization** which is an **on-policy**, policy gradient method.
 Other popular algorithm are:
@@ -11,7 +13,7 @@ Other popular algorithm are:
 -   **"Vanilla" Policy Gradient** methods which have poor data efficiency and robustness.
 -   **Trust Region / natural Policy gradient** methods (such as TRPO) which has a similar data efficiency and performance compared to PPO, while being more complicated [[Schulman et al., 2017](references.md#schulman2017ppo)].
 
-### On-policy vs Off-policy
+## On-policy vs Off-policy
 
 An **on-policy** algorithm does not use old data.
 In our case it means that one batch of simulation episodes will one be used to train the next policy,
@@ -23,7 +25,7 @@ Nonetheless it increases learning stability.
 > These algorithms directly optimize [...] policy performance and it works out mathematically that you need on-policy data to calculate the updates. So, this family of algorithms trades off sample efficiency in favor of stability—but you can see the progression of techniques (from VPG to TRPO to PPO) working to make up the deficit on sample efficiency. <br/>
 > \-- [Algorithms, OpenAI SpinningUp](https://spinningup.openai.com/en/latest/user/algorithms.html#the-on-policy-algorithms)
 
-### Policy Gradient Methods
+## Policy Gradient Methods
 
 Let's define some common notations in reinforcement learning:
 
@@ -42,7 +44,7 @@ Then this gradient estimate is used in a stochastic gradient ascent algorithm. T
 When training we will alternate between running simulation environments to generate a batch of sample (CPU/RAM bottlenecked)
 and optimization (GPU).
 
-## Proximal Policy Optimization
+# Proximal Policy Optimization
 
 Proximal Policy Optimization is a policy gradient method for reinforcement
 learning developed by OpenAI [[Schulman et al., 2017](references.md#schulman2017ppo)].

diff --git a/docs/index.md b/docs/index.md
@@ -31,13 +31,19 @@ serial communications capability.
 These servomotors are able to measure motor torque and speed, and are easy to
 use with a serial port.
 
+Even though the embedded computer has two free serial ports, getting all sensors values of 18 servomotors take an average of 40 ms, see [more details there](use_motors.md#how-slow-is-it).
+This means Kraby may be too slow to do proper torque control, that is why we try to use them in position control.
+
 These servomotors are similar to the more popular **Dynamixel AX-12**.
 
 ### Simulation environment included
 
-An [OpenAI Gym](https://gym.openai.com/) environment is available.
+[OpenAI Gym](https://gym.openai.com/) environments are available and packaged as [gym-kraby](https://pypi.org/project/gym-kraby/) on PyPi.
 It uses [BulletPhysics](https://github.com/bulletphysics/bullet3) simulator
-with [an URDF description](https://github.com/erdnaxe/kraby/blob/master/gym_kraby/data/hexapod.urdf) of the robot.
+with [an URDF description](https://github.com/erdnaxe/kraby/blob/master/gym_kraby/data/hexapod.urdf) of the robot,
+see [more details there](gym_environments.md).
+
+![OpenAI Gym environment](img/env_demo.jpg)
 
 * * *
 

diff --git a/docs/install_nanopi_linux.md b/docs/install_nanopi_linux.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Compile NanoPi linux kernel with MPU9250 module
 
 As of may 2020, only the official NanoPi kernel supports NanoPi Neo4 GPU and VPU.
@@ -103,7 +109,7 @@ then `ssh pi@10.42.0.1`.
 !!! Note
 
     You can plug wired Internet access
-	and NetworkManager will automatically use and share this connection.
+    and NetworkManager will automatically use and share this connection.
 
 ## Test the MPU9250
 

diff --git a/docs/training_one_leg.md b/docs/training_one_leg.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Training one robot leg
 
 This section gives some example and draws some conclusions about

diff --git a/docs/transfer_real_world.md b/docs/transfer_real_world.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Preparing transfer to real world
 
 ## Using bigger timesteps

diff --git a/docs/urdf_description.md b/docs/urdf_description.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # URDF description
 
 The **Unified Robot Description Format** (URDF) is an XML format
@@ -7,9 +13,13 @@ by the Robotic Operating System project (ROS).
 Kraby URDF description is available at
 <https://github.com/erdnaxe/kraby/blob/master/gym_kraby/data/hexapod.urdf>.
 
-* * *
+!!! Note "Do not use SDF"
+
+    This project started with a SDFormat description of the robot in Gazebo.
+    Despite PyBullet being able to load SDF files, the support is not as good as URDF files
+    and some simulation parameters were impossible to input.
 
-## Editing and building the URDF
+## Editing and building the URDF with Jinja templating
 
 To simplify URDF editing and to avoid input errors,
 the project uses Jinja2[^xacro] templates to generate the URDF.
@@ -18,8 +28,6 @@ You may edit files under
 then execute
 [gym_kraby/data/generate_urdf.py](https://github.com/erdnaxe/kraby/tree/master/gym_kraby/data).
 
-* * *
-
 ## Computing 3d-printed part inertia
 
 [Meshlab](http://www.meshlab.net/) is able to compute a inertia tensor from
@@ -62,3 +70,19 @@ For more information, see
 <http://gazebosim.org/tutorials?tut=inertia&cat=build_robot>.
 
 [^xacro]: [Xacro](http://wiki.ros.org/xacro) could also be an option, but it requires to install the ROS toolchain.
+
+# PyBullet integration
+
+Now that our robot is fully described in URDF, we may load it in BulletPhysics using PyBullet Python bindings.
+
+```Python
+import pybullet as p
+
+p.connect(p.GUI)  # Open new physic server with GUI
+p.setGravity(0, 0, -9.81)  # No, we are still on earth
+p.setAdditionalSearchPath(getDataPath())  # Add pybullet_data
+p.loadURDF("plane.urdf")  # Load a ground
+p.loadURDF("hexapod.urdf")  # Load the full robot
+```
+
+You may then use `p.setJointMotorControlArray` to control motors.
diff --git a/docs/use_motors.md b/docs/use_motors.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Send and receive data from servomotors
 
 The NanoPi NEO4 has five 3.3V UART that can go up to 1.5 Mbauds/s.

diff --git a/docs/use_mpu9250.md b/docs/use_mpu9250.md
@@ -1,3 +1,9 @@
+**Table of content**:
+
+[TOC]
+
+* * *
+
 # Fetch raw data from MPU9250 sensors
 
 Download, install and enable `iiod` server on NanoPi,

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -13,7 +13,7 @@ nav:
       - Use the internal motion unit: use_mpu9250.md
       - Use the servomotors: use_motors.md
   - Simulation:
-      - URDF description: urdf_description.md
+      - Robot simulation: urdf_description.md
       - Learning environments: gym_environments.md
       - Learning algorithm: implementations_ppo.md
       - Training one leg: training_one_leg.md