Introduction to the FreiCar Nodes
In the following, we'll give you a short overview of the ROS nodes we've developed over the last year for the FreiCar project. We'll introduce them in more detail as the course continues.
Note it is not possible to exhaustively test all these nodes in an academical environment. If you run into any bugs, send a message to one of your supervisors along with the the steps required to reproduce the it.
1. FreiCar Agent
This is the base node for all agents. Currently, it:
- Sends
Track
requests at start and shutdown - Publishes
FreiCarStatus
messages - Publishes
FreiCarLocalization
messages - Publishes a 3D model for visualization on RVIZ
2. FreiCar Carla Proxy
This node handles all the necessary tasks that are related to the simulator:
- Spawning the agent in CARLA
- Setting up the sensors and publishing their information
- Publishing the received pose on tf (simulated agents only)
- Removing the agent from simulation at shutdown
The sensor definition for each agent is a yaml file located at freicar_carla_proxy/param/sensors.yaml
. You can read more about carla sensors here.
3. FreiCar Carla Agent
This node spawns an arbitrary number of scripted agents in the environment. These agents generate random plans and follow them while obeying right of way rules and avoiding collisions. They perform these tasks by using the FreiCarAgentLocalization
messages from other agents.
Use
After compiling the node, you can start it with:
rosrun freicar_carla_agent freicar_carla_agent_node <number-of-agents> <seed>
The random seed is an optional argument. Providing it will change the behavior of the agents, i.e. where they spawn and how they plan.
4. FreiCar Chaperone
The chaperone node is responsible for making sure the agents do not collide with each other. It also makes sure the agents remain inside a specified boundary polygon.
The chaperone node also serves Track
requests. These help the chaperone node keep track of all the running agents and uses their tf information to predict where they might end up in the next few seconds.
5. FreiCar Common
This node serves as a reference for all the messages, services and shared headers in our stack. If you're familiar with ROS, you'd know that sharing any type of code between two packages is a tedious task. For large projects, it is much easier to create a single package that is find_package()
ed in every CMakeLists.txt.
5.1. Messages
The following messages are used in the FreiCar project. You can click on each one to see the message file.
5.1.1. FreiCarAgentLocalization
Each agent is required to publish this message at ~10Hz+ on the car_localization
topic. This information is currently only used by the scripted agents. Each message contains the name of the agent, the uuid of the current lane it's on, its offset along that lane, its velocity and 3D pose. With the simulated cars, the 3D pose is recieved from unreal and published as a ros::tf message.
Note At the beginning, you will receive the ground truth pose from the tf. As the course goes on, you will replace it with the output of your localization node. This message however still has to be filled with ground truth data. Currently this task is done by the freicar_agent node.
5.1.2. FreiCarControl
This is a reserved message, used by the administrator to suspend or release agents.
5.1.3. FreiCarGoTo
These messages are sent over the freicar_goto
. They specify a certain [lane, lane offset] or [x, y, heading] as a goal. The agent is then supposed to plan to the requested position and drive there.
5.1.4. FreiCarHalt
All agents must subscribe to 'halt'. These messages usually come from the chaperone node to prevent a collision with other agents. When this message is received, the agent is supposed to stop as soon as possible. The message contains the name of the agents involved as well as a basic reason why the agent was suspended.
5.1.4. Resume
The chaperone node publishes the names of the agents that are allowed to continue after being suspended. The message is just a string, published on resume
. As with the FreiCarHalt message, all agents must subscribe to this topic.
5.1.5. FreiCarStatus
Each agent must publish a message of this type on freicar_status
at least once every second. The admin GUI uses these messages to provide an overview of all running agents. Currently, they are published by freicar_agent, but this could change as the we progress.
5.2. Services
You can think of services as bidirectional ROS message. We currently have two services.
5.2.1. Track Request
Track requests are served by the chaperone node. Each agent must send a track request at initialization, stating its name, the name of its tf frame and whether it's a scripted agent. The latter is only true for the scripted agents in the freicar_carla_agent node. As the agent is shutting down, it must send another request with bool track
set to false. Currently, freicar_agent handles sending these track requests.
5.2.2. WayPoint Request
This is a deprecated service in freicar_map
. It has the same functionality as freicar::planning::lane_follower::GetPlan(...)
. It'll most likely be removed in a future commit.
5.3. Shared Headers
These headers contain enums that are used by other nodes.
5.3.1. halt_type.h
enum HaltType : unsigned char {
CORRIDOR_INTERSECT,
COLLISION,
DISABLED,
OUT_OF_BOUNDS,
ADMIN_ORDER,
NONE
};
An instance of this enum is sent with each FreiCarHalt message to indicate the reason behind suspension.
5.3.2. planner_cmd.h
enum PlannerCommand : unsigned char {
LEFT = 1, // go left if possible, fail at the junction otherwise
RIGHT = 2, // go right if possible, fail at the junction otherwise
STRAIGHT = 3, // go straight if possible, fail at the junction otherwise
RANDOM = 4, // choose a random direction
POINT = 5, // lane-star planner to a specific point
DIRECT = 6, // direct path strategy
EMPTY = 7 // empty plan
};
This enum is used by planners to specify the command.
6. FreiCar Joy
This node is used in tandem with others to enable joystick controls for a simulated agent. An example can be seen in freicar_agent/launch/sim_agent.launch
.
Supported Joysticks
The controller_type
parameter controls which joystick template the node uses. We've only tested the node with xbox360 and ps4 joysticks but feel free to add your own definition.
7. FreiCar Map
This node contains the core map structure and additional services that are built on top of it. You can find a more detailed explanation here.
8. FreiCar Setting
This node is responsible for applying the simulation settings and setting a couple of global ROS parameters.
8.1. YAML File
The CARLA API exposes 3 settings for the simulation. They are read from freicar_setting/param/carla_settings.yaml.
no rendering
If no-render-mode
is set to true, the simulator will stop rendering completely. This obviously uses less resources but also means the camera images will not be available.
This is not the same as headless rendering.
simulated steps per second
sim-steps-per-second
determines the desired number of simulated steps per second. To achieve acceptable physics simulation, the number should be at least 10. If set to 0, the simulation will run at full speed. This will naturally lead to variable delta time between the steps.
Note: This does not determine the simulator's FPS, although it can affect it. It also doesn't determine the amount of data you get from the sensors. Those are set in the sensor description file.
synchronous mode
if synchronous
is set to true, the simulation server will not proceed until a Tick()
is received. Technically all CARLA clients can send it but this node is currently the only one responsible for the sake of consistency. Setting this to true will start a thread (currently deactivated) that tries to tick the server according to sim-steps-per-second
.
You can read more about world settings and client-server synchrony.
8.2. Parameters
The aforementioned settings are also set as global ROS parameters.
sim_sps
This defines the simulated steps per second. Other nodes (e.g. freicar_agent) use this as their thread's sleep value. If the simulator is trying to simulate the environment x
times per seconds, it makes sense for us to update our agents with the same frequency.
sim_sync_mode
Indicates whether the synchronous mode has been activated. So far, no node uses this information.
sim_norender
Indicates whether the no-render mode has been activated. So far, no node uses this information.
9. Raiscar Messages
This package contains low level messages for controlling the car. This package is from our old software framework and still needs to be renamed,