frc-docs icon indicating copy to clipboard operation
frc-docs copied to clipboard

Add comprehensive documentation for custom struct and protobuf serialization

Open jasondaming opened this issue 4 months ago • 1 comments

Summary

Creates comprehensive documentation with canonical examples for implementing custom struct and protobuf serializers. This addresses the issue where teams currently need to reference WPILib source code to understand how to create their own serializers.

Changes

New Documentation

  • custom-serialization.rst: Complete guide with step-by-step examples for both Java and C++
    • When to use struct vs protobuf serialization
    • Complete working example of custom struct implementation (RobotState class)
    • Complete working example of protobuf implementation (TargetInfo class)
    • How to use custom serializers with NetworkTables
    • How to use custom serializers with DataLog
    • How to use custom serializers with Epilogue annotations
    • Important considerations and best practices

Updated Files

  • networktables-intro.rst: Added explanation of struct/protobuf support with link to custom serialization docs
  • telemetry.rst: Documented struct/protobuf support with link to custom serialization guide
  • robot-telemetry-with-annotations.rst: Added link to custom serialization guide for StructSerializable types
  • index.rst: Added custom-serialization.rst to NetworkTables documentation index

Examples Provided

The documentation includes:

  • Complete, copy-pasteable Java examples for struct serialization
  • Complete C++ examples using template specialization
  • Protobuf examples with .proto file definitions
  • Real-world use cases (robot state, vision target info)
  • Integration examples with NetworkTables, DataLog, and Epilogue

Fixes #2820

jasondaming avatar Oct 07 '25 03:10 jasondaming

Missing Python examples for struct (protobuf not supported). Point claude at https://robotpy.readthedocs.io/projects/robotpy/en/stable/wpiutil.wpistruct/functions.html#wpiutil.wpistruct.make_wpistruct and https://github.com/robotpy/mostrobotpy/blob/main/subprojects/robotpy-wpiutil/tests/test_struct.py for how to make custom python structs.

virtuald avatar Oct 07 '25 03:10 virtuald