From c1fc86033a4b5ebda451de657fc2546eb3f431fb Mon Sep 17 00:00:00 2001 From: CoolSpy3 Date: Thu, 30 May 2024 05:32:45 -0700 Subject: [PATCH] [sim] Clarify Sim CAN Device Documentation (#6679) --- .../java/edu/wpi/first/hal/SimDevice.java | 9 + .../java/edu/wpi/first/hal/SimDeviceJNI.java | 3 + hal/src/main/native/include/hal/SimDevice.h | 12 ++ .../halsim_ws_core/doc/hardware_ws_api.md | 8 +- simulation/halsim_ws_core/doc/wpilib-ws.yaml | 187 ++++++++++-------- 5 files changed, 128 insertions(+), 91 deletions(-) diff --git a/hal/src/main/java/edu/wpi/first/hal/SimDevice.java b/hal/src/main/java/edu/wpi/first/hal/SimDevice.java index 4c57d05595..7f1491c5b6 100644 --- a/hal/src/main/java/edu/wpi/first/hal/SimDevice.java +++ b/hal/src/main/java/edu/wpi/first/hal/SimDevice.java @@ -39,6 +39,9 @@ public class SimDevice implements AutoCloseable { * instances of the same device are desired, recommend appending the instance/unique identifier in * brackets to the base name, e.g. "device[1]". * + *

Using a device name of the form "Type:Name" will create a WebSockets node with a type value + * of "Type" and a device value of "Name" + * *

null is returned if not in simulation. * * @param name device name @@ -59,6 +62,9 @@ public class SimDevice implements AutoCloseable { * convenience method that appends index in brackets to the device name, e.g. passing index=1 * results in "device[1]" for the device name. * + *

Using a device name of the form "Type:Name" will create a WebSockets node with a type value + * of "Type" and a device value of "Name" + * *

null is returned if not in simulation. * * @param name device name @@ -76,6 +82,9 @@ public class SimDevice implements AutoCloseable { * convenience method that appends index and channel in brackets to the device name, e.g. passing * index=1 and channel=2 results in "device[1,2]" for the device name. * + *

Using a device name of the form "Type:Name" will create a WebSockets node with a type value + * of "Type" and a device value of "Name" + * *

null is returned if not in simulation. * * @param name device name diff --git a/hal/src/main/java/edu/wpi/first/hal/SimDeviceJNI.java b/hal/src/main/java/edu/wpi/first/hal/SimDeviceJNI.java index fdf09b4435..6941db3b27 100644 --- a/hal/src/main/java/edu/wpi/first/hal/SimDeviceJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/SimDeviceJNI.java @@ -16,6 +16,9 @@ public class SimDeviceJNI extends JNIWrapper { * instances of the same device are desired, recommend appending the instance/unique identifier in * brackets to the base name, e.g. "device[1]". * + *

Using a device name of the form "Type:Name" will create a WebSockets node with a type value + * of "Type" and a device value of "Name" + * *

0 is returned if not in simulation. * * @param name device name diff --git a/hal/src/main/native/include/hal/SimDevice.h b/hal/src/main/native/include/hal/SimDevice.h index e5e3324f9d..158f53b421 100644 --- a/hal/src/main/native/include/hal/SimDevice.h +++ b/hal/src/main/native/include/hal/SimDevice.h @@ -48,6 +48,9 @@ extern "C" { * appending the instance/unique identifier in brackets to the base name, * e.g. "device[1]". * + * Using a device name of the form "Type:Name" will create a WebSockets node + * with a type value of "Type" and a device value of "Name" + * * 0 is returned if not in simulation. * * @param name device name @@ -664,6 +667,9 @@ class SimDevice { * recommend appending the instance/unique identifier in brackets to the base * name, e.g. "device[1]". * + * Using a device name of the form "Type:Name" will create a WebSockets node + * with a type value of "Type" and a device value of "Name" + * * If not in simulation, results in an "empty" object that evaluates to false * in a boolean context. * @@ -679,6 +685,9 @@ class SimDevice { * brackets to the device name, e.g. passing index=1 results in "device[1]" * for the device name. * + * Using a device name of the form "Type:Name" will create a WebSockets node + * with a type value of "Type" and a device value of "Name" + * * If not in simulation, results in an "empty" object that evaluates to false * in a boolean context. * @@ -695,6 +704,9 @@ class SimDevice { * channel in brackets to the device name, e.g. passing index=1 and channel=2 * results in "device[1,2]" for the device name. * + * Using a device name of the form "Type:Name" will create a WebSockets node + * with a type value of "Type" and a device value of "Name" + * * If not in simulation, results in an "empty" object that evaluates to false * in a boolean context. * diff --git a/simulation/halsim_ws_core/doc/hardware_ws_api.md b/simulation/halsim_ws_core/doc/hardware_ws_api.md index cfeef53b3d..ca6c233c02 100644 --- 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 diff --git a/simulation/halsim_ws_core/doc/wpilib-ws.yaml b/simulation/halsim_ws_core/doc/wpilib-ws.yaml index 2e2d173a79..e688db8ae1 100644 --- 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"