= 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="digital_008", trigger="hold") self._addComponent(Button, command=self.selectPreviousConfig, key="digital_009", trigger="hold") self._addComponent(Button, command=self.robot.incBodyPosition, key="digital_004", mapper=MapperSetValue(dz=+5)) self._addComponent(Button, command=self.robot.incBodyPosition, key="digital_005", mapper=MapperSetValue(dz=-5)) self._addComponent(Joystick, configs="walk", command=GaitSequencer().walk, keys=("analog_02", "analog_03", "analog_00"), mapper=MapperWalk()) self._addComponent(Axis, configs="body", command=self.robot.setBodyExtraPosition, key="analog_00", mapper=MapperSetMultiply('yaw', coef=-15)) self._addComponent(Axis, configs="body", command=self.robot.setBodyExtraPosition, key="analog_03", mapper=MapperSetMultiply('pitch', coef=-15)) self._addComponent(Axis, configs="body", command=self.robot.setBodyExtraPosition, key="analog_02", mapper=MapperSetMultiply('roll', coef=15)) }}} We won't deep into details, here; refer to the [wiki:UserGuideGit#Controllers documentation] and [wiki:Tutorial5AdvancedRemoteControlUsage tutorial 5] 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 [wiki: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 of 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 [wiki: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. In the [wiki:Tutorial2UsingThe3DSimulator next tutorial], we will create a virtual robot, using the 3D simulator classes.