Testing and Debugging Behavior

Behavior is one of the hardest modules to test and debug, as it takes in a TON of information from every different system and the response of the behavior is obviously very dependent on the current state of the world, which can be hard to replicate exactly. For this reason, it is important to make extensive use of the Logging system so that issues that come up during testing can be investigated after the fact by looking at the logs.

Relevant Files

Most of the behavior files that are used are all contained in the BodyFSM folder. As mentioned in the Behavior Overview, BodyFSM.lua controls the high level flow of the behavior system by defining a number of states and the transitions between those states. Most of the other files in that folder are individual states that will contain at least 3 functions: entry(), update(), and exit(). The entry() function gets called when the state is transition to and so first time setup is performed here. The update() function is called once per clock cycle so the majority of the state computations occur here. If the update() function returns a string, that string will determine which new state it transitions to, according to the BodyFSM.lua file. The exit() function gets called when leaving a state and so cleanup functions can be done here.

Around the behavior code you will see lots of references to things like gcm, vcm, wcm, mcm, etc. These modules are shared memory buffers for the game (gcm), vision (vcm), world (scm), and motion (mcm). They are essentially large dictionary files that can be accessed with specific keys (ie. gcm.get_team_role() or wcm.get_pose()). All these functions are doing is getting or setting the relevant information in the shared memory. For more advanced information you can look at this page.

Tips and Tracks

• To test for behavior issues, run test matches and observe any strange or poor behavior. If you keep the main screen open in the terminal (use screen -r main after you run the code) you will see debug printouts (that also get logged) of which state the robot is currently in. If you see strange behavior, note the state that the robot was in and what went wrong. Then go find the code for that state and see if you can determine why the problem is happening. Being able to narrow a problem down to a specific state is a very helpful part of debugging behavior.
• If the behavior transitions to the wrong state, the problem is with the state it was in before the transition. Look for the return value that caused the transition and see if you can determine why the code reached that section.
• If the problem is that the robot is moving to the wrong position or with the wrong speed, then the problem is likely in targetpose.lua or velgeneration.lua.
• It is also very possible that you will find that the behavior problem is actually an issue with a different module like locomotion, localization, or vision. In that case you have two options: try to fix the underlying issue or try to patch the behavior module to minimize or avoid the problem. The first method is obviously better but, in a pinch, the second method can work well.
• The Behavior Config File contains a LOT of parameters that can be tuned. Most of them are organized by what state they are for but if you aren't sure what they do, the best thing to do is use Github to search for that parameter and find the file it is used in and what it does in that file.
• Test something for a defender specifically for a defender can be tricky due to role switching, so you can use the parameter team.force_defender to make that player always a defender
• The team.use_team_ball parameter specifies whether a player should trust the team ball if they haven't seen the ball themselves after a certain time. If they do use the team ball, their behavior should continue as normal (i.e. not go into search mode) even though they can't see the ball themselves.
• When making changes to behavior, make sure that you test the change in such a way that the file or section of code you changed actually gets run. For example, if you change something in the bodySearch.lua function, make sure that you test the robot in such a way that the FSM actually gets into the bodySearch state. This will help verify that you change works and, more importantly, will make sure the code doesn't crash in that state. Lua is an interpreted language and therefore problems are not detected until runtime, which can sometimes take a bit more work to test properly.