The User Manual is currently being ported to the Wiki. The following sections are available, or at least have some content from the manual. These sections are candidates for a WikiBooks style manual as well.
- About SimSpark
- Log Files
- Simulation Update Loop
- Soccer Simulation
- Running a Simulation
- Network Protocol
- Developers Manual
The following sections of the PDF manual will not be carried over as they are either out of date or obsoleted by superior content already on the wiki. Please dispute these points on this page, or email Drew/the mailing list.
- Section 1.3 - About this manual
- Section 1.4 - Readers guide to the manual
- Section 2.3 - The sample client
- Section 2.4 - Available simulations
- Section 3.1 - download/installation
- Section 4.2.3 - deprecated effectors (drive/catch/kick)
NOTE the PDF version is out of date and contains some incorrect information. This wiki is a superset of the information in the PDF.
A user's manual is included in the source code distribution in directory doc/users of the source tree. You'll need pdflatex to build it from it's LaTeX sources.
The following PDF files are available:
This document contains enough information to get the software built and running, and to implement a team of robots from scratch in any language that supports TCP sockets.
Errata and Clarifications
This section applies to the the above document (version 1.2, dated January 2010) when considered for version 0.6.3 of SimSpark. Below are a collection of questions and points that could be addressed in the documentation for clarity.
Section 4.1.2 - General Perceptors
This section does not state what units the various orientations are in. Are they degrees, radians or a ratio between 0 and 1? Assuming that they're in degrees (like all other angles in the protocol) does it represent the current rate of rotation (in degrees per second), or the number of degrees rotated during the last cycle (20ms)?
- Gyro values are in degrees per second and represents the current angular velocity.
Section 4.1.3 - Soccer Perceptors
The format of vision perceptor s-expressions in a format that is not valid in SimSpark version 0.6.3 (possibly only when using the Nao robot which uses RestrictedVisionPerceptor.) The observed format is:
(See (<name> (pol <distance> <angle1> <angle2>)) (P (team <teamname>) (id <playerID>) (<part> (pol <distance> <angle1> <angle2>)) (<part> (pol <distance> <angle1> <angle2>)) ) )
The difference being the introduction of <part> which, by observation of the server's behaviour, seems to include:
...and presumably others. Maybe someone can include a full list here from the source, and in turn update the PDF.
Note also that the description of the angle1 and angle2 are misleading. The value of angle1 depends upon the orientation of the camera and so zero does not always point to the opponent's goal. Perhaps the old VisionPerceptor (with 360 degree view) behaved differently. If so, this section of the documentation should be divided in two.
- No, the visual values are relative in both VisionPerceptor and RestrictedVisionPerceptor. So, zero does not point to the opponent's goal.
"The camera is currently located at the center of the robot’s torso."
This is not the case when using the Nao model, where the camera is located within the head and is subject to movements of the head relative to the torso.
Additionally, what are the exact locations of the landmarks?
Are the flags exactly on the corners of the field?
- What is the height at which flags are sighted? Z=0?
- What is the height at which goals are sighted? Z=GoalHeight?
Furthermore, the frequency of the vision perceptors is not the same as the HingeJoint Perceptor. The message generated by vision perceptor will be sent every 3 simulation cycles(0.06s).
The manual states:
"The first percept you get from this perceptor additionally tells you about some of the game variables, like ball weight and field size."
The server version 0.6.3 does not seem to display this additional data. The manual does not provide information about the format of such data either.
Section 4.2.1 - General Effectors
HingeJoint & UniversalJoint Effectors
The user manual incorrectly states that the numeric value passed with these commands represents the change in angle of the joint. Instead, the value passed here is an angular velocity. If the requested velocity needs more force than the maximum allowed force for the joint, then the maximum force will be used instead.
Section 4.2.2 - Soccer Effectors
The coordinate system used when beaming is not clear from the manual. It appears as though a diagram is missing.
It might also be clearer to state: The beam effector allows a player to position itself on the field before the start of each half.
Section 8.1 - Soccerbot
The manual incorrectly states that Soccerbot is the most advanced and currently used model.
The angle limits for each degree of freedom are not tabulated, as they are for Nao.
Section 8.2 - Nao Model
Here are a few questions that could be clarified in the documentation for people (like me) who are creating a Nao bot:
- Under what circumstances (if any) are the Nao's battery and temperature reported? I have never seen these messages.
- Currently, never! They were used in the spheres age, and they might be used in future again.
- Under what circumstances (if any) are the Nao's TouchPerceptors triggered? I have never seen these message. Does the Nao use these?
- No. Nao uses ForceResistancePerceptor instead.
Figure 8.6 has been copied from some Nao literature and doesn't match the orientation used in rcssserver3d. The robot is constructed facing the y-axis. The x-axis in figure 8.6 (from Aldebaran) is the y-axis in SimSpark (from here).