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:
- TheÂ BotÂ receives orders and perform actions
- Â 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.
@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 !
@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
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.
Next time, this will be the “SirBot Ranger in a Nutshell”, explaining an exciting feature of SirBot:Â event management…