[sim] Clarify Sim CAN Device Documentation (#6679)

2026-06-19 00:41:43 +00:00 · 2024-05-30 05:32:45 -07:00
parent 9782abbcb1
commit c1fc86033a
5 changed files with 128 additions and 91 deletions
--- a/simulation/halsim_ws_core/doc/hardware_ws_api.md
+++ b/simulation/halsim_ws_core/doc/hardware_ws_api.md
@@ -99,7 +99,7 @@ The “hardware“ (which might be a full-fledged 3D simulation engine, a physic

 A 3-axis accelerometer.

-C++/Java implementation note: these are created as either BuiltInAccelerometer or SimDevice nodes where the device name is prefixed by ``"Accel:"``, for example ``"Accel:ADXL362[1]"``.  The BuiltInAccelerometer uses a device name of ``"BuiltInAccel"``.
+C++/Java implementation note: these are created as either BuiltInAccelerometer or SimDevice nodes where the device name is prefixed by ``"Accel:"``. For example, the device ``"Accel:ADXL362[1]"`` would have a device value of ``ADXL362[1]``.  The BuiltInAccelerometer uses a device name of ``"BuiltInAccel"``.

 | Data Key     | Type    | Description                                          |
 | ------------ | ------- | ---------------------------------------------------- |
@@ -194,7 +194,7 @@ The basic analog output just sends a voltage.

 Duty Cycle inputs are commonly used for absolute encoders.  The position is accumulated over multiple rotations.

-C++/Java implementation note: these are created as SimDevice nodes where the device name is prefixed by ``"DutyCycle:"``, for example ``"DutyCycle:DutyCycleEncoder[1]"``.
+C++/Java implementation note: these can be created through the API as SimDevice nodes where the device name is prefixed by ``"DutyCycle:"``. For example, the device ``"DutyCycle:DutyCycleEncoder[1]"`` would have a device value of ``DutyCycleEncoder[1]``.

 | Data Key         | Type    | Description                      |
 | ---------------- | ------- | -------------------------------- |
@@ -223,7 +223,7 @@ A relative encoder.  For absolute encoders, use ``"DutyCycle"``.

 A single axis or 3-axis gyro.  Single axis gyros only use the X angle parameter.

-C++/Java implementation note: these are created as SimDevice nodes where the device name is prefixed by ``"Gyro:"``, for example ``"Gyro:ADXRS450[1]"``.
+C++/Java implementation note: these can be created created as SimDevice nodes where the device name is prefixed by ``"Gyro:"``. For example, the device ``"Gyro:ADXRS450[1]"`` would have a device value of ``ADXRS450[1]``.

 | Data Key          | Type    | Description                                               |
 | ----------------- | ------- | --------------------------------------------------------- |
@@ -322,7 +322,7 @@ CAN messages all use a device value of ``"DeviceType[Number]"``, where the Devic

 Many of the CAN messages use the same data key/values as other standard messages.  They are separately namespaced to make it easier for implementations to separate them from main robot controller messages.

-C++/Java implementation note: these are created as SimDevice nodes where the device name is prefixed by the message name and ``":"``, for example ``"CANMotor:Controller[1]"``.
+C++/Java implementation note: these can be created through the API as SimDevice nodes where the device name is prefixed by the message name and ``":"``. For example, ``"CANMotor:Controller[1]"`` would create a device with a type value of ``CANMotor`` and a device value of ``Controller[1]``.

 #### CANMotor

--- a/simulation/halsim_ws_core/doc/wpilib-ws.yaml
+++ b/simulation/halsim_ws_core/doc/wpilib-ws.yaml
@@ -56,6 +56,13 @@ components:
            - $ref: "#/components/schemas/relayData"
            - $ref: "#/components/schemas/solenoidData"
            - $ref: "#/components/schemas/roborioData"
+            - $ref: "#/components/schemas/canmotorData"
+            - $ref: "#/components/schemas/canencoderData"
+            - $ref: "#/components/schemas/cangyroData"
+            - $ref: "#/components/schemas/canaccelData"
+            - $ref: "#/components/schemas/canainData"
+            - $ref: "#/components/schemas/candioData"
+            - $ref: "#/components/schemas/candutycycleData"
            - $ref: "#/components/schemas/simdeviceData"

  schemas:
@@ -692,11 +699,11 @@ components:
      properties:
        type:
          type: string
-          description: "Dummy type used for SimDevice type with device=CANMotor:*"
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
          const: CANMotor
        device:
          type: string
-          description: "Should have the form CANMotor:ControllerClassName[id]"
+          description: "Should have the form ControllerClassName[id]"
        data:
          type: object
          description: "CANMotor Data"
@@ -738,11 +745,11 @@ components:
      properties:
        type:
          type: string
-          description: "Dummy type used for SimDevice type with device=CANEncoder:*"
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
          const: CANEncoder
        device:
          type: string
-          description: "Should have the form CANEncoder:ControllerClassName[id]"
+          description: "Should have the form EncoderClassName[id]"
        data:
          type: object
          description: "CANEncoder Data"
@@ -757,92 +764,98 @@ components:
              type: number
              description: "Velocity in rotations per second"

+    cangyroData:
+      type: object
+      required:
+      - type
+      - device
+      properties:
+        type:
+          type: string
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
+          const: CANGyro
+        device:
+          type: string
+          description: "Should have the form GyroClassName[id]"
+        data:
+          $ref: "#/components/schemas/gyroData/properties/data"
+
+    canaccelData:
+      type: object
+      required:
+      - type
+      - device
+      properties:
+        type:
+          type: string
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
+          const: CANAccel
+        device:
+          type: string
+          description: "Should have the form AccelClassName[id]"
+        data:
+          $ref: "#/components/schemas/accelData/properties/data"
+
+    canainData:
+      type: object
+      required:
+      - type
+      - device
+      properties:
+        type:
+          type: string
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
+          const: CANAIn
+        device:
+          type: string
+          description: "Should have the form AnalogInputClassName[id]"
+        data:
+          $ref: "#/components/schemas/aiData/properties/data"
+
+    candioData:
+      type: object
+      required:
+      - type
+      - device
+      properties:
+        type:
+          type: string
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
+          const: CANDIO
+        device:
+          type: string
+          description: "Should have the form DIOClassName[id]"
+        data:
+          $ref: "#/components/schemas/dioData/properties/data"
+
+    candutycycleData:
+      type: object
+      required:
+      - type
+      - device
+      properties:
+        type:
+          type: string
+          description: Device Type (e.g. DIO/AI/PWM/Encoder etc)
+          const: CANDutyCycle
+        device:
+          type: string
+          description: "Should have the form DutyCycleClassName[id]"
+        data:
+          $ref: "#/components/schemas/dutycycleData/properties/data"
+
    simdeviceData:
      type: object
      required:
      - type
      - device
-      oneOf:
-      - properties:
-          type:
+      properties:
+        type:
+          type: string
+          const: SimDevice
+        device:
+          type: string
+        data:
+          type: object
+          additionalProperties:
            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "(?!(DutyCycle|CAN(Motor|Encoder|Gyro|Accel|AIn|DIO|DutyCycle)):.+).+"
-          data:
-            type: object
-            additionalProperties:
-              type: string
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "DutyCycle:.+"
-          data:
-            $ref: "#/components/schemas/dutycycleData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANMotor:.+"
-          data:
-            $ref: "#/components/schemas/canmotorData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANEncoder:.+"
-          data:
-            $ref: "#/components/schemas/canencoderData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANGyro:.+"
-          data:
-            $ref: "#/components/schemas/gyroData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANAccel:.+"
-          data:
-            $ref: "#/components/schemas/accelData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANAIn:.+"
-          data:
-            $ref: "#/components/schemas/aiData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANDIO:.+"
-          data:
-            $ref: "#/components/schemas/dioData/properties/data"
-      - properties:
-          type:
-            type: string
-            const: SimDevice
-          device:
-            type: string
-            format: "CANDutyCycle:.+"
-          data:
-            $ref: "#/components/schemas/dutycycleData/properties/data"