Changes between Initial Version and Version 1 of Tutorial1FirstRobot

Timestamp:

Nov 22, 2017, 8:45:17 AM (8 years ago)

Author:

fma

Comment:

--

Tutorial1FirstRobot

@@ +1 @@
+= Tutorial 1: First robot =
+
+''Files for this tutorial are available in [https://framagit.org/fma38/Py4bot/tree/master/py4bot/examples/tutorial_1 py4bot/examples/tutorial_1/]. But don't just copy them here: write them from scratch, following the tutorial.''
+
+First, we create a new empty dir in our home dir:
+
+{{{
+$ mkdir tutorial_1
+$ cd tutorial_1
+}}}
+
+All usefull classes are available from the '''{{{api.py}}}''' module. So, we just have to import things from here. Let's create a '''{{{hexapod.py}}}''' file to put our code, and import what we are going to use in this tutorial:
+
+{{{
+#!python
+
+# -*- coding: utf-8 -*-
+
+from py4bot.api import *
+}}}
+
+Now, let's create the robot! A multi-legs robot is mainly build from a body, and several legs.
+
+We also need to create an ''actuator pool'', which contains all legs joints actuators, in order to move them synchronized. In our example, actuators are standard servos, and we use the '''Veyron''' board, from '''DFRobot''', to drive them:
+
+{{{
+#!python
+
+import settings
+
+
+class Hexapod(Robot):
+    def _createBody(self):
+        return Body(settings.LEGS_ORIGIN)
+
+    def _createLegs(self):
+        legs = {}
+        legIk = {}
+        for legIndex in settings.LEGS_INDEX:
+            legs[legIndex] = Leg3Dof(legIndex, {'coxa': Coxa(), 'femur': Femur(), 'tibia': Tibia()}, settings.FEET_NEUTRAL[legIndex])
+            legIk[legIndex] = Leg3DofIk(settings.LEGS_GEOMETRY[legIndex])
+
+        return legs, legIk
+
+    def _createActuatorPool(self):
+        driver = Veyron()
+        pool = ServoPool(driver)
+
+        for leg in self._legs.values():
+
+            # Create joints actuators
+            num = settings.LEGS_SERVOS_MAPPING[leg.index]['coxa']
+            servo = Servo(leg.coxa, num, **settings.SERVOS_CALIBRATION[num])
+            pool.add(servo)
+
+            num = settings.LEGS_SERVOS_MAPPING[leg.index]['femur']
+            servo = Servo(leg.femur, num, **settings.SERVOS_CALIBRATION[num])
+            pool.add(servo)
+
+            num = settings.LEGS_SERVOS_MAPPING[leg.index]['tibia']
+            servo = Servo(leg.tibia, num, **settings.SERVOS_CALIBRATION[num])
+            pool.add(servo)
+
+        return pool
+}}}
+
+As you can see, we just implemented 3 virtual methods, {{{_createBody()}}}, {{{_createLegs()}}} and {{{_createActuatorPool()}}}.
+
+Also note that we used some values from the '''{{{settings.py}}}''' module. This module is just a simple way to centralise the configuration of our hexapod. We will describe this module later.
+
+To drive a robot, we need a remote control. In this tutorial, we are going to use an old gamepad, a [http://www.thrustmaster.com/en_IN/products/firestorm-dual-analog-3 Thrustmaster Firestorm Dual Analog 3]. As I own such gamepad, I already added support in Py4bot:
+
+{{{
+#!python
+
+class Gamepad(RemoteControl):
+    def _createFrontend(self):
+        return Thrustmaster(settings.THRUSTMASTER_PATH)
+
+    def _buildComponents(self):
+        self._addConfig("walk")
+        self._addConfig("body")
+
+        self._addComponent(Button, command=self.selectNextConfig, key="button_008", trigger="hold")
+        self._addComponent(Button, command=self.selectPreviousConfig, key="button_009", trigger="hold")
+
+        self._addComponent(Button, command=self.robot.incBodyPosition, key="button_004", mapper=MapperSetValue(dz=+5))
+        self._addComponent(Button, command=self.robot.incBodyPosition, key="button_005", mapper=MapperSetValue(dz=-5))
+        self._addComponent(Joystick, configs="walk", command=GaitSequencer().walk, keys=("analog_02", "analog_03", "analog_00"), mapper=MapperWalk())
+
+        self._addComponent(Analog, configs="body", command=self.robot.setBodyExtraPosition, key="analog_00", mapper=MapperSetMultiply('yaw', coef=-15))
+        self._addComponent(Analog, configs="body", command=self.robot.setBodyExtraPosition, key="analog_03", mapper=MapperSetMultiply('pitch', coef=-15))
+        self._addComponent(Analog, configs="body", command=self.robot.setBodyExtraPosition, key="analog_02", mapper=MapperSetMultiply('roll', coef=15))
+}}}
+
+We won't deep into details, here; refer to the [[UserGuideGit#Controllers|documentation]] for more informations about remote controls. This is an important part of the framework, and you  can do very smart things, like having several configurations, using several remotes for the same robot...
+
+Now, let's create our robot:
+
+{{{
+#!python
+
+def main():
+    def addGait(gaitClass, gaitName):
+        group = settings.GAIT_LEGS_GROUPS[gaitName]
+        params = settings.GAIT_PARAMS['default']
+        for key1, value1 in settings.GAIT_PARAMS[gaitName].items():
+            for key2, value2 in value1.items():
+                params[key1][key2] = value2
+        gait = gaitClass(gaitName, group, params)
+        GaitManager().add(gait)
+
+    addGait(GaitTripod, "tripod")
+    addGait(GaitTetrapod, "tetrapod")
+    addGait(GaitRiple, "riple")
+    addGait(GaitWave, "metachronal")
+    addGait(GaitWave, "wave")
+    GaitManager().select("riple")
+
+    robot = Hexapod()
+
+    remote = Gamepad(robot)
+
+    GaitSequencer().start()
+    remote.start()
+
+    robot.setBodyPosition(z=30)
+
+    robot.mainLoop()
+
+    remote.stop()
+    remote.join()
+    GaitSequencer().stop()
+    GaitSequencer().join()
+
+
+if __name__ == "__main__":
+    main()
+}}}
+
+First, we add a few pre-defined gaits, in order to make it walk. Then, we create the robot itself, the remote control, and start all this little world!
+
+== Settings ==
+
+Let's discuss about settings used in the previous part. See the [[UserGuideGit#Geometrydefinition|user guide]] for the body/legs geometry conventions used.
+
+{{{
+#!python
+
+LEGS_INDEX = ('RF', 'RM', 'RR', 'LR', 'LM', 'LF')
+}}}
+
+{{{LEGS_INDEX}}} contains the names used to define legs; they can be freely chosen, but these values must be used as keys for other params.
+
+{{{
+#!python
+
+LEGS_GEOMETRY = {
+    'RM': {'coxa': 25, 'femur': 45, 'tibia': 65},
+    'RF': {'coxa': 25, 'femur': 45, 'tibia': 65},
+    'LF': {'coxa': 25, 'femur': 45, 'tibia': 65},
+    'LM': {'coxa': 25, 'femur': 45, 'tibia': 65},
+    'LR': {'coxa': 25, 'femur': 45, 'tibia': 65},
+    'RR': {'coxa': 25, 'femur': 45, 'tibia': 65}
+}
+}}}
+
+{{{LEGS_GEOMETRY}}} dict contains the lengths of the different parts of the legs, in mm.
+
+{{{
+#!python
+
+LEGS_ORIGIN = {
+    'RM': {'x':  50., 'y':   0., 'gamma0' :   0.},
+    'RF': {'x':  35., 'y':  80., 'gamma0' :  30.},
+    'LF': {'x': -35., 'y':  80., 'gamma0' : 150.},
+    'LM': {'x': -50., 'y':   0., 'gamma0' : 180.},
+    'LR': {'x': -35., 'y': -80., 'gamma0' : 210.},
+    'RR': {'x':  35., 'y': -80., 'gamma0' : 330.},
+}
+}}}
+
+{{{LEGS_ORIGIN}}} dict contains the positions and orientation of the origin of the legs: {{{(x, y)}}} defines the center of rotation of '''coxa''' joint, and {{{gamma0}}} is the angle of the legs at neutral position.
+
+{{{
+#!python
+
+FEET_NEUTRAL = {
+    'RM': LEGS_GEOMETRY['RM']['coxa'] + LEGS_GEOMETRY['RM']['femur'],
+    'RF': LEGS_GEOMETRY['RF']['coxa'] + LEGS_GEOMETRY['RF']['femur'],
+    'LF': LEGS_GEOMETRY['LF']['coxa'] + LEGS_GEOMETRY['LF']['femur'],
+    'LM': LEGS_GEOMETRY['LM']['coxa'] + LEGS_GEOMETRY['LM']['femur'],
+    'LR': LEGS_GEOMETRY['LR']['coxa'] + LEGS_GEOMETRY['LR']['femur'],
+    'RR': LEGS_GEOMETRY['RR']['coxa'] + LEGS_GEOMETRY['RR']['femur'],
+}
+}}}
+
+{{{FEET_NEUTRAL}}} dict contains the feet neutral positions af all legs. This is just the distance from the legs origins, in the ground plane, along leg X axis.
+
+{{{
+#!python
+
+LEGS_SERVOS_MAPPING = {
+    'RF': {'coxa':  0, 'femur':  1, 'tibia':  2},
+    'RM': {'coxa':  4, 'femur':  5, 'tibia':  6},
+    'RR': {'coxa':  8, 'femur':  9, 'tibia': 10},
+    'LR': {'coxa': 15, 'femur': 14, 'tibia': 13},
+    'LM': {'coxa': 19, 'femur': 18, 'tibia': 17},
+    'LF': {'coxa': 23, 'femur': 22, 'tibia': 21}
+}
+}}}
+
+{{{LEGS_SERVOS_MAPPING}}} is a table to map all joints to actuators nums.
+
+{{{
+#!python
+
+SERVOS_CALIBRATION = {
+     0: {'offset':   0, 'neutral': 1500, 'ratio':  0.090},  # coxa  leg RF
+     1: {'offset': 180, 'neutral': 1500, 'ratio':  0.090},  # femur leg RF
+     2: {'offset':  90, 'neutral': 1500, 'ratio':  0.090},  # tibia leg RF
+
+     4: {'offset':   0, 'neutral': 1500, 'ratio':  0.090},  # coxa  leg RM
+     5: {'offset': 180, 'neutral': 1500, 'ratio':  0.090},  # femur leg RM
+     6: {'offset':  90, 'neutral': 1500, 'ratio':  0.090},  # tibia leg RM
+
+     8: {'offset':   0, 'neutral': 1500, 'ratio':  0.090},  # coxa  leg RR
+     9: {'offset': 180, 'neutral': 1500, 'ratio':  0.090},  # femur leg RR
+    10: {'offset':  90, 'neutral': 1500, 'ratio':  0.090},  # tibia leg RR
+
+    15: {'offset':   0, 'neutral': 1500, 'ratio':  0.090},  # coxa  leg LR
+    14: {'offset': 180, 'neutral': 1500, 'ratio': -0.090},  # femur leg LR
+    13: {'offset':  90, 'neutral': 1500, 'ratio': -0.090},  # tibia leg LR
+
+    19: {'offset':   0, 'neutral': 1500, 'ratio':  0.090},  # coxa  leg LM
+    18: {'offset': 180, 'neutral': 1500, 'ratio': -0.090},  # femur leg LM
+    17: {'offset':  90, 'neutral': 1500, 'ratio': -0.090},  # tibia leg LM
+
+    23: {'offset':   0, 'neutral': 1500, 'ratio':  0.090},  # coxa  leg LF
+    22: {'offset': 180, 'neutral': 1500, 'ratio': -0.090},  # femur leg LF
+    21: {'offset':  90, 'neutral': 1500, 'ratio': -0.090},  # tibia leg LF
+}
+
+}}}
+
+{{{SERVOS_CALIBRATION}}} contains some calibration:
+
+* {{{offset}}} is the angle between the servo reference and the real angle. See the [[FAQ#Howisgeometrydefined|FAQ]] for the real angles definition;
+* {{{neutral}}} is the pulse value for the neutral position of the servo;
+* {{{ratio}}} is angle per pulse width.
+
+Offsets may vary, depending how you mount the servos. Same, ratio sign may have to be inverted on one side, if you have a symmetrical design; all angle are always computed using trigonometric direction (CCW).
+
+See the [[UserGuideGit#Servoscalibration|user guide]] how to fine tune servos calibration.
+
+Finally:
+
+{{{
+#!python
+
+GAIT_LEGS_GROUPS = {
+    'tripod':      (('RM', 'LF', 'LR'), ('RF', 'LM', 'RR')),
+    'tetrapod':    (('RR', 'LM'), ('RF', 'LR'), ('RM', 'LF')),
+    'riple':       (('RR',), ('LM',), ('RF',), ('LR',), ('RM',), ('LF',)),
+    'metachronal': (('RR',), ('LM',), ('RF',), ('LR',), ('RM',), ('LF',)),
+    'wave':        (('RR',), ('RM',), ('RF',), ('LR',), ('LM',), ('LF',))
+}
+
+GAIT_PARAMS = {
+    'default': {
+        'length': {
+            'min': 5.,
+            'max': 30.
+        },
+        'angle': {
+            'min': 0.5,
+            'max': 5.
+        },
+        'height': {
+            'min': 20.,
+            'max': 40.
+        },
+        'speed': {
+            'min': 25.,
+            'max': 250.
+        }
+    },
+    'tripod': {
+        'length': {
+            'max': 40.
+        },
+        'angle': {
+            'max': 10.
+        }
+    },
+    'tetrapod': {},
+    'riple': {},
+    'metachronal': {},
+    'wave': {}
+}
+}}}
+
+{{{GAIT_LEGS_GROUPS}}} contains the legs grouped together and controlled at the same time during the gait usage.
+
+Note that we need to define sequences, so don't forget the comma to define a tuple with a unique element.
+
+{{{GAIT_PARAMS}}} contains some additional gaits params:
+
+* {{{length}}} is the distance (range) each leg will move for an entire cycle when the robot translate at full speed;
+* {{{angle}}} is the angle (range) each leg will turn for an entire cycle when the robot rotate at full speed;
+* {{{height}}} is the height (range) the leg will lift up;
+* {{{speed}}} is the speed (range).
+
+These values must be adjusted for each robot, to avoid legs collisions.
+
+{{{
+#!python
+
+THRUSTMASTER_PATH = "/dev/input/by-id/usb-Mega_World_Thrustmaster_dual_analog_3.2-event-joystick"
+}}}
+
+No need for further explanations.