February 2007

You are currently browsing the monthly archive for February 2007.

So here’s the first tutorial about the SirBot Project. Now it’s been released, we can start learning how to use it…

In this tutorial, you’ll learn how to use one of the most important feature of SirBot: the protocol declaration syntax

1. BTW, what’s a Protocol ?

The basic architecture of a robot built with SirBot is quite simple:

 

  1. The Bot receives orders and perform actions
  2.  A Core System, on a PC (or the like, an iPaq, etc…), actually sends those orders.

This means (almost) everything first comes from the Core system, not from the Bot. This is because it would dramatically make the bot too much complex: you’d need to define a kind of server within the bot, which would listen to connections and orders, would have the ability to dynamically program actions, would store every piece of information, would handle events, etc…

Because we (at least me) can feel the cold wind of fear while imagining how to do this with a basic microcontroller, the simplest way to achieve these is to keep them on a PC, and do the mimimal things within the bot. Those minimal things are called primitive actions (also previously called procotol unit, that is the smallest unit of a protocol definition. Nomenclature changed when the “almost” big rewrite occured). They represent what the bot can do, in its most primitive form (!).

Ex: a bot has two motors associated to two wheels, so it can moves around. From the bot perspective, the primitive actions are “move motor A /B forward/backward”. It doesn’t understand what “turn left !!!” means. Because “turn left !!!” i done moving one motor in a way, the other in the other way. That is, “turn left !!!” is the composition of two primitive actions. Why implementing this composed, complex action in the bot ? To keep it simple, this type of action will be kept in the core system, on the PC.

So, only primitive actions are implemented within the bot, all others complex actions are in the PC. Now, how to order the bot “turn left !!!” ? Simply by telling it, from the PC: this complex action will be translated into the corresponding primitive actions. Only these primitive actions will be sent to the bot, as it can only understand this kind of action.

A SirBot Protocol is the definition of complex actions and primitive actions:

  • Complex actions are just the composition of other complex actions, or primitive actions
  • Primitive actions are what the bot can actually do, thus what will actually be sent to robot.

In practice, primitive actions is where SirBot will do most of its job, by abstracting what’s been sent and how it’s been sent to the bot. This is where most of the protocol definition stands, as it defines how to send requests to the bot and receive responses from the bot

The Protocol Definition Syntax

The Protocol Definition Syntax declares primitive actions in a protocol. Because SirBot is python-based, an action (primitive or complex) is just a class method. The difference comes from the fact class methods for primitive actions are decorated with @connector. Using this decorator, we tell SirBot what to send to the bot, and what is expected as a response.

Example 1

@connector(char="w")
def move_servo(self,servo_id,position):
	pass

# "bot" is a protocol object, that is, what's representing the robot
bot.move_servo(ROTATIVE_SERVO,117)
  •  When we call the move_servo method, SirBot and its @connector decorator will translate a python call into something meaningful to the bot. How does it works ? The char argument specifies the action character: when the bot receives the letter “w”, it knows it’ll have to move servo. The protocol also defines how a list of arguments can be sent to the bot (not shown here in this piece of code). The @connector actually build a string, and send it to the bot. The important thing is we, human, don’t care about how the translaction occurs, how the communication is processed, etc… we just write python code !

Example 2

@connector(char="r",lreturn=1)
def ir_range(self):
	'''Take distance measure with a IR ranger'''
	pass

(request,response) = bot.ir_range()
  • Same as above, expect we declare, with lreturn, that when calling this method, we’re expecting a result. Precisely, the length of the returned chars from the bot must be 1. Exactly. Or it’ll raise an error, informing something bad happened… Also note we get a returned tuple: a request and a response object  (when calling a primitive action, we always get request/response objects, whether we’re expecting a returned value). The request object contains every piece of information used to build what’s actually been sent to the bot. The response object is what we’ve received from the bot, that is, the distance. If no returned value is expected, the content the response object will be None.

2. Defining the TamaBot Daycare Protocol

Enough theory, let’s get into a real-world example: the TamaBot DayCare. Basically, the TamaBot is robot with 2 servos: one for the horizontal axis, the other of the vertical one. Both represents a kind of arm, which is able to act on the Tamagotchi buttons. That’s all… Well, that’s demystification but that’s all :)

tamabot_overview.jpg TamaBot_IDCard.png

Moving a servo is a primitive action, and thus needs a @connector. The following picture shows all the process being done when ordering the bot to move a servo to a specified position, using the dedicated @connector.

That’s all for now… You can get the TamaBot Daycare sources by downloading the SirBot Project archive here. You may note not all the complex actions are coded, so you can get the full source there. It will be included in the next release.

Next time, this will be the “SirBot Ranger in a Nutshell”, explaining an exciting feature of SirBot: event management…