capnp struct definitions and messaging used in comma ecosystem
Go to file
Shane Smiskol 7fa84db484
Update messaging/impl_msgq.cc
2024-02-14 19:11:32 -08:00
.github/workflows add --minimal build flag (#523) 2023-08-24 14:00:32 -07:00
include remove java.capnp 2021-10-11 14:35:46 -07:00
logger fix suppression for older cppcheck 2022-03-13 22:22:32 -07:00
messaging Update messaging/impl_msgq.cc 2024-02-14 19:11:32 -08:00
site_scons/site_tools cython dependency scanner 2021-01-11 14:15:29 -08:00
visionipc Revert "move vipc to a prefix folder" (#581) 2024-02-08 13:38:38 -08:00
.dockerignore Run scons in CI (#14) 2019-11-20 16:32:42 -08:00
.gitignore include from project root (#402) 2022-12-31 14:19:29 -08:00
.pre-commit-config.yaml pre-commit: autoupdate hooks (#568) 2024-02-09 19:43:23 -08:00
Dockerfile CI: pylint to ruff (#512) 2023-08-07 15:55:35 -07:00
LICENSE Add the same license on this repo as openpilot (#78) 2020-11-25 11:12:13 +01:00
README.md Update README.md (#533) 2023-09-15 10:44:30 -07:00
SConscript add --minimal build flag (#523) 2023-08-24 14:00:32 -07:00
SConstruct add --minimal build flag (#523) 2023-08-24 14:00:32 -07:00
__init__.py messaging cleanup (#582) 2024-02-09 16:16:02 -08:00
car.capnp deprecate curvature steer control type (#579) 2024-02-02 23:07:53 -08:00
codecov.yml Coverage analysis in CI (#75) 2020-07-29 00:33:42 -07:00
custom.capnp Custom events reserved for forks (#449) 2023-05-23 20:44:17 +02:00
generate_javascript.sh initial commit, internal from 6/13/19 2019-06-13 12:06:15 -07:00
legacy.capnp bring qcomgnss back from deprecation 2022-03-23 15:50:02 -07:00
log.capnp deprecate unused clocks fields 2024-02-13 14:03:55 -08:00
maptile.capnp get rid of the java (#199) 2021-09-21 14:48:35 -07:00
pyproject.toml update ruff settings to new format 2024-02-11 21:25:14 -08:00
services.py update clocks frequency 2024-02-13 13:12:54 -08:00

README.md

What is cereal? cereal tests codecov

cereal is both a messaging spec for robotics systems as well as generic high performance IPC pub sub messaging with a single publisher and multiple subscribers.

Imagine this use case:

  • A sensor process reads gyro measurements directly from an IMU and publishes a sensorEvents packet
  • A calibration process subscribes to the sensorEvents packet to use the IMU
  • A localization process subscribes to the sensorEvents packet to use the IMU also

Messaging Spec

You'll find the message types in log.capnp. It uses Cap'n proto and defines one struct called Event.

All Events have a logMonoTime and a valid. Then a big union defines the packet type.

Best Practices

  • All fields must describe quantities in SI units, unless otherwise specified in the field name.
  • In the context of the message they are in, field names should be completely unambiguous.
  • All values should be easy to plot and be human-readable with minimal parsing.

Maintaining backwards-compatibility

When making changes to the messaging spec you want to maintain backwards-compatibility, such that old logs can be parsed with a new version of cereal. Adding structs and adding members to structs is generally safe, most other things are not. Read more details here.

Custom forks

Forks of openpilot might want to add things to the messaging spec, however this could conflict with future changes made in mainline cereal/openpilot. Rebasing against mainline openpilot then means breaking backwards-compatibility with all old logs of your fork. So we added reserved events in custom.capnp that we will leave empty in mainline cereal/openpilot. If you only modify those, you can ensure your fork will remain backwards-compatible with all versions of mainline cereal/openpilot and your fork.

Pub Sub Backends

cereal supports two backends, one based on zmq and another called msgq, a custom pub sub based on shared memory that doesn't require the bytes to pass through the kernel.

Example

import cereal.messaging as messaging

# in subscriber
sm = messaging.SubMaster(['sensorEvents'])
while 1:
  sm.update()
  print(sm['sensorEvents'])

# in publisher
pm = messaging.PubMaster(['sensorEvents'])
dat = messaging.new_message('sensorEvents', size=1)
dat.sensorEvents[0] = {"gyro": {"v": [0.1, -0.1, 0.1]}}
pm.send('sensorEvents', dat)