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

= User guide (git) =

''This documentation tries to follow the development 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.

Refer to the [htdocs:api/index.html complete API] for more details about classes/methods used.

== Architecture ==

The main parts of the framwork are:

* the '''robot''' itself;
* the '''gait sequencer''';
* one or more '''remote controllers'''.

[[Image(design_simple.png​, 300px)]]

Each of these parts runs as separate thread. For now, the robot does nothing in its main loop, ans so, can be used for further devs (automatic stabilization...).

== 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, 300px)]]

=== 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 robot 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 parallel 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, 300px)]]

''Todo: improve drawing''

=== Feet coordinates systems ===

They are the last coordinates systems used in this framework, and they are 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 leg ====

* '''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, 300px)]]

==== 4 DoF leg ====

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

[[Image(IK4DoF.png, 300px)]]

== Robot ==

The '''robot''' is responsible for all static computation, ie implements the '''inverse Kinematic'''. It also manages the body position, which can move along the 3 axes, and rotate arround 3 axes.

As shown in the [[Tutorials|tutorials]], to implement a custom robot, you need to write a new class which inherits from {{{Robot}}}, and overload several methods:

* {{{_createBody(self)}}}
* {{{_createLegs(self)}}}
* {{{_createActuatorPool(self)}}}

This is where you choose how many legs your robot has, and how many Degrees of Freedom (DoF) each leg has.

The {{{Robot}}} object has some usefull methods you will have to use in order to make your robot do smart things:

* {{{setBodyPosition(self, x=None, y=None, z=None, yaw=None, pitch=None, roll=None)}}}

This method can only be called when the robot is in ''idle'' state.

It translates/rotates the body, and the new position is kept.

* {{{incBodyPosition(self, dx=0., dy=0., dz=0., dyaw=0., dpitch=0., droll=0.)}}}

This methods can be called in any robot state.

Like the previous method, you can adjust the body position, by little steps.

* {{{setBodyExtraPosition(self, x=None, y=None, z=None, yaw=None, pitch=None, roll=None)}}}

This method can only be called when the robot is in ''idle'' state.

Like the first method, you can translate/rotate the body. The resulting position of the body is the combination of the bodyPosition and the bodyExtraPosition.

The {{{setBodyPosition()}}} is mainly used at startup, to set a pre-defined position of the body. The {{{setBodyExtraPosition()}}}, however, can be usefull to move the body arround its default position, without loosing it.

* incFeetNeutral(self, dneutral)

This method can only be called when the robot is in ''idle'' state.

It allows you to extend/reduce the ''length'' of the legs. Each time this method is called, the robot will do a ''static walk'', in order to put all feet to there new neutral position.

== Actuators, Pools and Drivers ==

{{{Actuator}}}s are the objects which really move the {{{Joint}}}s.

{{{Pool}}}s are used to group {{{Actuator}}}s, mainly to moved them in a synchronized way. It is possible to have the same {{{Actuator}}} in several {{{Pool}}}s, but, of course, you won't be able to drive both {{{Pool}}}s at the same time.

A {{{Pool}}} uses a {{{Driver}}} to really make the {{{Actuator}}}s move.

=== Servos calibration ===

'''{{{py4bot-gui-servocal.py}}}''' script can be used to fine tune servos, and generate the {{{SERVOS_CALIBRATION}}} dict.

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

== Gaits and !GaitSequencer ==

The '''Gaits''' and '''!GaitSequencer''' implement the dynamic part of the movements, ie the gait itself. It computes the successive feet positions in order to make the robot walk.

[[Image(design_gait.png, 300px)]]

==  Remote controls ==

The {{{RemoteControl}}} translates user orders to {{{Robot}}}/{{{GaitSequencer}}} methods calls.

[[Image(design_remote-control.png, 300px)]]

As you can see on the UML diagram, a {{{RemoteControl}}} object uses {{{Components}}}; a {{{Component}}} can be a {{{Button}}}, a {{{Switch}}} an {{{Analog}}}, or a {{{Joystick}}}.

{{{RemoteControl}}} has the following virtual methods which must be override in a custom remote control class:

* {{{_createFrontend(self)}}}

This method must return an input frontend.

* {{{_buildComponents(self)}}}

Here, we create the components of the remote control

The following methods are used to setup the remote control:

 * {{{_addConfig(self, config)}}}
 * {{{_addComponent(self, cls, **kwargs)}}}

(See below)

Then, a number of objects/methods can be used as components commands:

 * selectPreviousConfig(self)
 * selectNextConfig(self)
 * {{{robot}}}

The {{{robot}}} object is used to reach the robot methods from the components.

=== Components ===

'''Py4bot''' implements different components to build a custom remote control. All components 

==== Button ====

{{{Button}}} is a simple push button, with several ''triggers'', in order to control its behavior:

 * click
 * double-click
 * press
 * release
 * hold
 * double-hold

Default trigger is ''click'' (you must press and release the button quickly).

==== Switch ====

{{{Switch}}} is a button toggling between 2 states when you press it.

==== Analog ====

{{{Analog}}} handles a single analog axis.

==== Joystick ====

{{{Joystick}}} combines several {{{Analog}}} axes.

=== Configurations and modifiers ===

There are many commands to control the robot, and not enough physical buttons/axis on a gamepad. So, a solution is to multiplex these buttons/axis. There are 2 ways to do that: ''configurations'' and ''modifiers''. ''Configurations'' allow us to change the entire mapping; ''modifiers'' only changes a button meaning.

To create several ''configurations'', use the {{{_addConfig()}}} method. This method take a string as argument, the name of the config.

=== Mappers ===

'''Mappers''' are simple objects helping to adapt params from '''!RemoteControl''' '''Components''' output to '''Robot'''/'''!GaitSequencer''' methods input.

Custom '''Mappers''' can be defined.

=== Add a new Frontend ===

{{{Frontend}}}s are responsible of generating states. This is where specific controllers implementation live.

There are some usefull {{{Frontend}}}s defined in '''Py4bot''', mainly USB-based, using ''event'' interface. See [Tutorial4AddInputFrontendSupport tutorial 4] to see how to add a new frontend.