[[PageOutline(2-5, Table of Contents, floated)]]

= User guide (git) =

''This documentation tries to follow the developement version of Py4bot. It may or may not be up-to-date.''

For installation instructions, see [InstallationGuide here].

== Usage overview ==

As Py4bot is a framework, you will find here a description of the main things you need to understand to write your own applications.

Together with this page, have a look at the [htdocs:api/index.html complete API].

== Architecture ==

The main parts of the framwork are:

* the robot itself;
* the gait sequencer;
* some remote controllers.

== Geometry definition ==

There are several coordinates systems involved when computing maths in order to make a robot walk; it is important to understand how they are defined. All these systems are cartesian.

In the image below, X axis is in cyan, Y axis is in magenta, and Z axis is in yellow:

[[Image(coordinates_systems.png, 500px, nolink)]]

=== Robot coordinates system ===

This coordinates system is attached to the robot itself:

* the origin is at the center of the robot, in the ground plane
* X and Y axes are in the ground plane
* Y axis is the back-to-front axis of the robot
* Z axis points up

=== Body coordinates system ===

This coordinates system is attached to the body. It is defined from the body coordinates system:

* the origin is at the center of the body
* X and Y axes define a plane parallel to the body
* Y axis is the back-to-front axis of the body
* Z define the top side of the body

This system is used to define the position of the body in the robot coordinates system, allowing it to move along the 6 DoF (3 translations, 3 rotations).

=== Legs coordinates systems ===

These coordinates systems are attached to the legs, so each leg has its own coordinates system. They are defined from the body coordinates system:

* the origin is at the coxa joint
* X and Y axes define a plane parallele to the body
* X axis is along the coxa of the leg
* Z points up

To summurize, from the body coordinate system, the legs coordinates systems are translated by '''(x, y)''' and rotated by '''gamma0''' arround Z:

[[Image(body_legs.png, 500px, nolink)]]

''Todo: improve drawing''

=== Gait coordinates system ===

''Or feet coordinates system?''

There is the last coordinates system, which is used by the gaits, to make to robot walk. They are defined from the robot coordinates system:

* the origins are at the center of the feet, in the ground plane
* X and Y axes are in the ground plane
* Y axis is the back-to-front axis of the robot
* Z axis points up

To summurize, from the robot coordinate system, the gaits coordinates systems are translated by '''(x, y)'''.

=== Inverse Kinematic ===

The Inverse kinematic is the the kinematic equations of a robot to determine the joints parameters that provide a desired position of leg (foot).

Here are the angles involved.

==== 3 DoF legs ====

* '''gamma''': angle of the leg in the the body X/Y plane (angle between body X axis and leg X axis)
* '''alpha''': angle of the femur in the leg X/Z plane (angle between coxa and femur)
* '''beta''': angle of the tibia in the leg X/Z plan (angle between femur and tibia)

[[Image(IK3DoF.png, 500px, nolink)]]

==== 4 DoF leg ====

* '''tars''':  angle of the tars in the leg X/Z plan (angle between tibia and tars)

[[Image(IK4DoF.png, 500px, nolink)]]

== Robot ==

== Drivers ==

=== Servos calibration ===

You can use the '''{{{py4bot-gui-servocal.py}}}''' to fine tune your servos calibration, and generate the {{{SERVOS_CALIBRATION}}} dict.

[[Image(py4bot-gui-servocal.png, 500px, nolink)]]

If you launch this tool in the dir. containing your '''{{{settings.py}}}''' config file with a previous {{{SERVOS_CALIBRATION}}} dict., it will be used as default values.
== Gaits ==

== Controllers ==

=== Add a new Frontend ===