This section describes a simple network API that Brainhat supports for interaction with robots and other processes. Set-up involves several steps:

1. Incorporating Command Processing into the Robot(s)
2. Identifying the Robot(s) to Brainhat
3. Telling Brainhat where to find the Robot(s) on the on the Network
4. Instructing Brainhat to Delegate Tasks to the Robot(s)

Sample robot server code (roboipc) can be found in the distribution. You can use it to test robot interaction with Brainhat without a robot. Simply compile and run.

Incorporating Command Processing

To start, the robot listens on a TCP/IP port (see sample server code), awaiting a connection from Brainhat. At some point, Brainhat will make a connection and (perhaps) delegate commands to the robot. When a command comes into the robot, it will look something like this:

 

start
tag=00004839
command=put
object=ball
color=red
target=bin
orientation=in
end

This could be the equivalent of a robot command: "put the red ball in the bin."

The tag value is a unique identifier that the robot and Brainhat share to track the state of a delegated command. We will see how it used, below.

The command is a primitive action that the robot will understand. Examples might be get, put or position. The vocabulary of verbs that the robot might use is virtually unlimited, and you may extend it as you like. External action verbs for robot (and other) commands are identified in the data files as children of a special concept called extaction, as in:

 

define	toget-1
	child		action
	label		to get
	child		extaction

Extaction verbs are organized the same as others, with an infinitive form and subordinate forms connected as children. They may be used for non-robot commands, just as any other verb.

Object is the object the robot is manipulating.

Target, when present, will be the object of the preposition for commands that specify a source or destination for an action. Likewise, orientation will be the preposition for those commands that specify a source or destination.

The sample above shows "color=red" as one of the elements of the command to the robot. "Color" is not a primitive for robot commands. Rather, "color" just happens to be non-prepositional attribute associated with the object in the example (the ball). Any other attribute might have been included as well. If the ball was big, for example, a attribute/value pair like "size=big" might have been part of the command. Accordingly, the number and variety of attribute/value pairs is unlimited.

How you dispatch commands within the robot depends the robot or service you have created. When the command is completed, the robot should inform Brainhat so that Brainhat can direct the robot to the next task and/or tell the speaker that the command is finished. Here's what you need to do: If the command completes successfully, the robot may simply send Brainhat an acknowledgement. The syntax for the successful completion is:

 

#####:Y

where "#####" represents the tag number taken from the command as delegated to the robot by Brainhat. The "Y" stands for "yes" (meaning completion was successful). To finish our example above, for instance, the robot would send Brainhat the message:

 

4839:Y

Upon receipt of the message, Brainhat would tell the speaker "the robot did put the ball in the bin." You may also change the "Y" to an "N" to signify failure:

 

4839:N

Brainhat will inform the speaker "the robot did not put the ball in the bin" and perform any follow-on action associated with the failure. You may tack on a reason as well, if you like:

 

4839:N:the ball is lost

Brainhat will report "the robot did not put the ball in the bin because the ball is lost."

Messages from the robot do not have to be associated with commands. At any time you can send Brainhat a message without a tag, such as

 

the water is cold

Brainhat will voice the message and incorporate it into the conversation just as if it had come from the user.

Note that the messages to Brainhat can come asynchronously, while Brainhat is busy doing other things; no sequencing is necessary. Likewise, you may issue many messages to Brainhat. They will be processed as they arrive.

Identifying the Robot(s) to Brainhat

Robots are special. Brainhat identifies robots by the fact that they are children of a concept called xrobot, defined among the required definitions. Here is how you might identify robby as a robot:

 

define	robby-1
	label		robby
	label		robby robot
	child		xrobot

At runtime, when you delegate commands to robby, Brainhat will be able to tell that robby robot is an instance of xrobot via the child command above.

Telling Brainhat where the Robot(s) are

Nominating the robots for Brainhat is just part of the job. Brainhat also needs to know how to find the robots on the network so that it can communicate. Particularly, Brainhat needs the IP address and port number of each participant. It learns these via English commands from you, or from the "brainhat.init" start-up file. As an example, I might say:

 

robby's address is 198.252.200.120


or


the address of robby is 198.252.200.120

The TCP port number, 4140, is implied, though you may explicitly choose a port by adding it to the address as in:

 

robby's address is 127.0.0.1:4140

As soon as you identify a robot to Brainhat, the program will attempt a connection. Successful, all subsequent communications to robby robot will go out to the address and port specified.

 

Tasks are delegated by issuing imperatives to the robots, or by telling Brainhat to tell a robot to do something:

 

robby put the ball in the water


or


tell robby to put the ball in the water

Once the command is given to Brainhat, it will be delegated to the waiting robot. (Just to review: the verb must be a child of extaction, the robot must be a child of xrobot, and the robot must be connected.) Of course, robots only become really useful when they can be left alone to complete a task. With Brainhat, you can mete out the components of a complex undertaking by combining robot execution with Brainhat's capability to exercise propositions.

 

If the speaker wants a thing then robby gets a thing.  
If robby got a thing then the speaker has a thing.

If the speaker is hungry then the speaker wants a hotdog.
If the speaker has a hotdog then the speaker wants a beer. 
If the speaker has food and the speaker has a beverage then tell 
the speaker that robby likes the speaker and ask if the speaker is happy.

The conversation starts when the speaker says "i'm hungry." Brainhat then delegates the jobs of getting a hotdog and beer to the robot. When both items are delivered, Brainhat asks if the speaker is happy. To try this scenario out, run a copy of roboipc, and tell Brainhat "robby's address is 127.0.0.1" Robot commands will appear in the roboipc window. Respond "#####:Y" to each of the robot requests as detailed above.

Other Interfaces

Brainhat has a an interprocess communication interface as described elsewhere on this site. There are other, less formal interfaces that you may use as well.

Mail

Brainhat can send email. (It cannot receive it yet, though this does seem like it might be useful....). Try this:

tell me that i am pretty
my address is <your email address>
mail me that you love me.

You should receive a piece of mail. If you want to gather information about a person or thing and then have it mailed back to you:

my address is <your email address>
if a thing is in the water then a thing is wet.
i saw the red ball in the water.
mail me the ball