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

=== Ground coordinates system ===

This coordinates system is attached to the ground; it is a fixed referential.

* the origin is somewhere on the ground
* X and Y axes define a plane parallel to the ground
* Z axis points up

=== Robot coordinates system ===

This coordinates system is attached to the robot itself.

* the origin is at the center of the robot
* X and Y axes define a plane parallel to the ground, so that Y axis is the back-to-front axis of the robot
* Z axis points up

In the ground coordinates system, the robot coordinates system is just translated in the X/Y plane, and rotated arround Z.

=== Body coordinates system ===

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

* the origin is at the center of the body
* X and Y axes define a plane parallel to the body, so that Y axis is the back-to-front axis of the body
* Z axis is orthogonal to X/Y

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 ===

This coordinates systems are attached to the legs, so each leg has its own coordinates system. They are defined in the body coordinates system.

* the origin is at the origin of the leg (usually the coxa joint)
* X axis is along the coxa of the leg
* X and Y axes are in the same plane as the one defined by the body X/Y axes
* Z axis is orthogonal to X/Y

To summurize, from the body coordinate system, the legs coordinates systems are translated in the X/Y plane and rotated arround Z.

The origin of a leg is defined as following, from the robot coordinates system:

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

''Todo: improve drawing''

=== Gait coordinates system ===

There is the last coordinates system, which is used by the gaits, to make to robot walk.

This coordinate systems is defined from the body coordinates system, and also translated along body X/Y axes, but not rotated arround Z.

=== 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)]]

== Gaits ==

== Controllers ==

=== Add a new Frontend ===