1"""
   2Venice is an open-source Micropython runtime for VEX V5 robots.
   3
   4```python
   5from venice import Motor, Gearset, Direction
   6import venice.vasyncio
   7
   8async def main():
   9    my_motor = Motor(
  10        1,
  11        Direction.FORWARD,
  12        Gearset.GREEN
  13    )
  14    my_motor.set_voltage(10.0)
  15vasyncio.run(main())
  16```
  17"""
  18
  19from __future__ import annotations
  20
  21from typing import ClassVar, List, Literal, Union
  22
  23
  24class RotationUnit:
  25    """Represents a unit of rotation for angles."""
  26
  27    RADIANS: ClassVar["RotationUnit"]
  28    """The rotation unit representing radians."""
  29
  30    DEGREES: ClassVar["RotationUnit"]
  31    """The rotation unit representing degrees."""
  32
  33    TURNS: ClassVar["RotationUnit"]
  34    """The rotation unit representing turns (revolutions)."""
  35
  36
  37RotationUnit.RADIANS = RotationUnit()
  38RotationUnit.DEGREES = RotationUnit()
  39RotationUnit.TURNS = RotationUnit()
  40
  41
  42class TimeUnit:
  43    """Represents a unit of time."""
  44
  45    MILLIS: ClassVar["TimeUnit"]
  46    """The time unit representing milliseconds."""
  47
  48    SECONDS: ClassVar["TimeUnit"]
  49    """The time unit representing seconds."""
  50
  51
  52TimeUnit.MILLIS = TimeUnit()
  53TimeUnit.SECONDS = TimeUnit()
  54
  55
  56class Direction:
  57    """A rotational direction."""
  58
  59    FORWARD: ClassVar["Direction"]
  60    """Rotates in the forward direction."""
  61
  62    REVERSE: ClassVar["Direction"]
  63    """Rotates in the reverse direction."""
  64
  65
  66Direction.FORWARD = Direction()
  67Direction.REVERSE = Direction()
  68
  69
  70class Gearset:
  71    """Internal gearset used by VEX Smart motors."""
  72
  73    RED: ClassVar["Gearset"]
  74    """36:1 gear ratio"""
  75
  76    GREEN: ClassVar["Gearset"]
  77    """18:1 gear ratio"""
  78
  79    BLUE: ClassVar["Gearset"]
  80    """6:1 gear ratio"""
  81
  82
  83Gearset.RED = Gearset()
  84Gearset.GREEN = Gearset()
  85Gearset.BLUE = Gearset()
  86
  87
  88class BrakeMode:
  89    """Determines the behavior a motor should use when braking with `AbstractMotor.brake`."""
  90
  91    COAST: ClassVar["BrakeMode"]
  92    """Motor never brakes."""
  93
  94    BRAKE: ClassVar["BrakeMode"]
  95    """Motor uses regenerative braking to slow down faster."""
  96
  97    HOLD: ClassVar["BrakeMode"]
  98    """Motor exerts force holding itself in the same position."""
  99
 100
 101BrakeMode.COAST = BrakeMode()
 102BrakeMode.BRAKE = BrakeMode()
 103BrakeMode.HOLD = BrakeMode()
 104
 105
 106class MotorType:
 107    """Represents the type of a Smart motor.
 108
 109    Either a 11W (V5) or 5.5W (EXP) motor."""
 110
 111    EXP: ClassVar["MotorType"]
 112    """A 5.5W Smart Motor"""
 113
 114    V5: ClassVar["MotorType"]
 115    """An 11W Smart Motor"""
 116
 117
 118class RotationSensor:
 119    """A rotation sensor plugged into a Smart Port.
 120
 121    The VEX V5 Rotation Sensor, measures the absolute position, rotation count,
 122    and angular velocity of a rotating shaft.
 123
 124    # Hardware Overview
 125
 126    The sensor provides absolute rotational position tracking from 0° to 360° with 0.088° accuracy.
 127    The sensor is composed of two magnets which utilize the
 128    [Hall Effect](https://en.wikipedia.org/wiki/Hall_effect_sensor) to indicate angular
 129    position. A chip inside the rotation sensor (a Cortex M0+) then keeps track of the total
 130    rotations of the sensor to determine total position traveled.
 131
 132    Position is reported by VEXos in centidegrees before being converted to a float
 133    in the given unit of rotation.
 134
 135    The absolute angle reading is preserved across power cycles (similar to a potentiometer), while
 136    the position count stores the cumulative forward and reverse revolutions relative to program
 137    start, however the *position* reading will be reset if the sensor loses power. Angular velocity
 138    is measured in degrees per second.
 139
 140    Like all other Smart devices, VEXos will process sensor updates every 10mS.
 141    """
 142
 143    def __init__(self, port: int, direction: Direction = Direction.FORWARD):
 144        """Creates a new rotation sensor on the given port.
 145
 146        Whether or not the sensor should be reversed on creation can be specified.
 147
 148        Args:
 149
 150        * port: The port number (1-21).
 151
 152        * direction: The direction of rotation. Defaults to forward.
 153        """
 154
 155    MIN_DATA_INTERVAL_MS: int = 5
 156    """The minimum data rate that you can set a rotation sensor to, in milliseconds."""
 157
 158    TICKS_PER_ROTATION: int = 36000
 159    """The amount of unique sensor readings per one revolution of the sensor."""
 160
 161    def position(self, unit: RotationUnit) -> float:
 162        """Returns the total accumulated rotation of the sensor over time, in
 163        the specified units.
 164
 165        Args:
 166
 167        * unit: The `RotationUnit` to use for the return value.
 168        """
 169        ...
 170
 171    def angle(self, unit: RotationUnit) -> float:
 172        """Returns the absolute angle of rotation measured by the sensor.
 173
 174        This value is reported from 0-360 degrees.
 175
 176        Args:
 177
 178        * unit: The `RotationUnit` to use for the return value.
 179        """
 180        ...
 181
 182    def set_position(self, angle: float, angle_unit: RotationUnit):
 183        """Sets the sensor's position reading.
 184
 185        Args:
 186
 187        * angle: The angle to set the sensor to.
 188        * angle_unit: The `RotationUnit` to use for the angle.
 189        """
 190        ...
 191
 192    def velocity(self) -> float:
 193        """Returns the sensor's current velocity in degrees per second."""
 194        ...
 195
 196    def reset_position(self):
 197        """Resets the sensor's position reading to zero."""
 198        ...
 199
 200    def set_direction(self, new_direction: Direction):
 201        """Sets the sensor to operate in a given `Direction`.
 202
 203        This determines which way the sensor considers to be “forwards”. You can use the marking on
 204        the top of the motor as a reference:
 205
 206        - When `Direction.FORWARD` is specified, positive velocity/voltage values will cause the
 207          motor to rotate **with the arrow on the top**. Position will increase as the motor rotates
 208          **with the arrow**.
 209        - When `Direction.REVERSE` is specified, positive velocity/voltage values will cause the
 210          motor to rotate **against the arrow on the top**. Position will increase as the motor
 211          rotates **against the arrow**.
 212
 213        Args:
 214
 215        * new_direction: The new `Direction` to set the sensor to.
 216        """
 217        ...
 218
 219    def direction(self):
 220        """Returns the `Direction` of this sensor."""
 221        ...
 222
 223    def status(self) -> int:
 224        """Returns the sensor's internal status code."""
 225        ...
 226
 227    def set_data_interval(self, interval: float, interval_unit: TimeUnit):
 228        """Sets the internal computation speed of the rotation sensor.
 229
 230        This method does NOT change the rate at which user code can read data off the sensor, as the
 231        brain will only talk to the device every 10mS regardless of how fast data is being sent or
 232        computed.
 233
 234        This duration should be above `RotationSensor.MIN_DATA_INTERVAL_MS` (5 milliseconds).
 235
 236        Args:
 237
 238        * interval: The new interval to set the sensor to.
 239        * interval_unit: The unit of the interval.
 240        """
 241
 242
 243class AbstractMotor:
 244    """A motor plugged into a Smart Port.
 245
 246    This is an abstract class supporting shared methods for both the 5W (Exp)
 247    and 11W motor variants. To create a motor, use the initializers of `ExpMotor`
 248    or `V5Motor`, respectively.
 249
 250    # Overview
 251
 252    The V5 Smart Motors come in two variants: [an 11W model](https://www.vexrobotics.com/276-4840.html),
 253    with interchangeable gear cartridges and [a 5.5W model](https://www.vexrobotics.com/276-4842.html),
 254    with a fixed gearing. The 11W motor supports three cartridge options, which will gear the motor
 255    down from its base RPM of 3600: a red cartridge providing 100 RPM output, a green cartridge for
 256    200 RPM, and a blue cartridge for 600 RPM. The 5.5W motor comes with a non-interchangeable 200
 257    RPM gear cartridge.
 258
 259    Smart Motors feature several integrated sensors, including an encoder for measuring the velocity
 260    and position of the motor, a temperature sensor for detecting overheats, and sensors for
 261    measuring output voltage, current, and efficiency.
 262
 263    Communication between a Smart motor and the V5 Brain occur at two different intervals. While
 264    the motor communicates with the Brain every 5 milliseconds (and commands can be written to the
 265    motor every 5mS), the Brain only reads data from the motor every 10mS. This effectively places
 266    the data *write* interval at 5mS and the data *read* interval at 10mS.
 267
 268    More in-depth specs for the 11W motor can be found [here](https://kb.vex.com/hc/en-us/articles/360060929971-Understanding-V5-Smart-Motors).
 269
 270    # Current Limitations
 271
 272    There are some cases where VEXos or the motor itself may decide to limit output current:
 273
 274    - **Stall Prevention**: The stall current on 11W motors is limited to 2.5A. This limitation
 275      eliminates the need for automatic resetting fuses (PTC devices) in the motor, which can
 276      disrupt operation. By restricting the stall current to 2.5A, the motor effectively avoids
 277      undesirable performance dips and ensures that users do not inadvertently cause stall
 278      situations.
 279
 280    - **Motor Count**: Robots that use 8 or fewer 11W motors will have the aforementioned current limit
 281      of 2.5A set for each motor. Robots using more than 8 motors, will have a lower default current limit
 282      per-motor than 2.5A. This limit is determined in VEXos by a calculation accounting for the number of
 283      motors plugged in, and the user's manually set current limits using `AbstractMotor.set_current_limit`. For
 284      more information regarding the current limiting behavior of VEXos, see [this forum post](https://www.vexforum.com/t/how-does-the-decreased-current-affect-the-robot-when-using-more-than-8-motors/72650/4).
 285
 286    - **Temperature Management**: Motors have an onboard sensor for measuring internal temperature.
 287      If the motor determines that it is overheating, it will throttle its output current and warn
 288      the user.
 289
 290    # Motor Control
 291
 292    Each motor contains a sophisticated control system built around a Cortex M0+ microcontroller.
 293    The microcontroller continuously monitors position, speed, direction, voltage, current, and
 294    temperature through integrated sensors.
 295
 296    The onboard motor firmware implements a set of pre-tuned PID (Proportional-Integral-Derivative)
 297    controllers operating on a 10-millisecond cycle for position and velocity control. Motors also
 298    have braking functionality for holding a specific position under load.
 299    """
 300
 301    WRITE_INTERVAL_MS: int = 5
 302    """The interval at which the Brain will send new packets to an `AbstractMotor`."""
 303
 304    def set_voltage(self, voltage: float):
 305        """Sets the motor's output voltage.
 306
 307        This voltage value spans from -12 (fully spinning reverse) to +12 (fully spinning forwards)
 308        volts, and controls the raw output of the motor.
 309
 310        Args:
 311
 312        - voltage: The output voltage of the motor in volts.
 313        """
 314        ...
 315
 316    def set_velocity(self, rpm: int):
 317        """Spins the motor at a target velocity.
 318
 319        This velocity corresponds to different actual speeds in RPM depending on the gearset used
 320        for the motor. Velocity is held with an internal PID controller to ensure consistent
 321        speed, as opposed to setting the motor's voltage.
 322
 323        Args:
 324
 325        - rpm: The desired target velocity in RPM.
 326        """
 327        ...
 328
 329    def brake(self):
 330        """Sets the motor's target to a given `BrakeMode`."""
 331        ...
 332
 333    def set_position_target(
 334        self, position: float, position_unit: RotationUnit, velocity: int
 335    ):
 336        """Sets an absolute position target for the motor to attempt to reach using its internal
 337        PID control.
 338
 339        Args:
 340
 341        - position: The desired position of the motor after the movement operation.
 342        - position_unit: The unit of the position.
 343        - velocity: The desired speed of the velocity in RPM during the movement operation
 344        """
 345        ...
 346
 347    def is_exp(self) -> bool:
 348        """Returns `True` if the motor is a 5.5W (EXP) Smart Motor."""
 349        ...
 350
 351    def is_v5(self) -> bool:
 352        """Returns `True` if the motor is an 11W (V5) Smart Motor."""
 353        ...
 354
 355    def max_voltage(self) -> float:
 356        """Returns the maximum voltage for the motor based off of its `MotorType`.
 357
 358        See `V5Motor.MAX_VOLTAGE` and `ExpMotor.MAX_VOLTAGE`."""
 359        ...
 360
 361    def velocity(self) -> float:
 362        """Returns the motor's estimate of its angular velocity in rotations per minute (RPM).
 363
 364        # Accuracy
 365
 366        In some cases, this reported value may be noisy or inaccurate, especially for systems where
 367        accurate velocity control at high speeds is required (such as flywheels). If the
 368        accuracy of this value proves inadequate, you may opt to perform your own velocity
 369        calculations by differentiating `AbstractMotor.position` over the reported internal timestamp
 370        of the motor (currently not exposed in the Venice API).
 371
 372        > For more information about Smart motor velocity estimation, see [this article](https://sylvie.fyi/sylib/docs/db/d8e/md_module_writeups__velocity__estimation.html).
 373
 374        # Note
 375
 376        This is the **estimated** velocity, not the **target** velocity. The Venice API currently does
 377        not mirror vexide's `Motor::target` so there is no way to get the target velocity.
 378        """
 379        ...
 380
 381    def power(self) -> float:
 382        """Returns the power drawn by the motor in Watts."""
 383        ...
 384
 385    def torque(self) -> float:
 386        """Returns the torque output of the motor in Nm."""
 387        ...
 388
 389    def voltage(self) -> float:
 390        """Returns the voltage the motor is drawing in volts."""
 391        ...
 392
 393    def raw_position(self) -> int:
 394        """Returns the most recently recorded raw encoder tick data from the motor's IME.
 395
 396        The motor's integrated encoder has a TPR of 4096. Gearset is not taken into consideration
 397        when dealing with the raw value, meaning this measurement will be taken relative to the
 398        motor's internal position *before* being geared down from 3600RPM.
 399
 400        Methods such as `AbstractMotor.reset_position` and `AbstractMotor.set_position` do not
 401        change the value of this raw measurement.
 402        """
 403        ...
 404
 405    def current(self) -> float:
 406        """Returns the electrical current draw of the motor in amps."""
 407        ...
 408
 409    def efficiency(self) -> float:
 410        """Returns the efficiency of the motor from a range of [0.0, 1.0].
 411
 412        An efficiency of 1.0 means that the motor is moving electrically while drawing no electrical
 413        power, and an efficiency of 0.0 means that the motor is drawing power but not moving."""
 414        ...
 415
 416    def current_limit(self) -> float:
 417        """Returns the current limit for the motor in amps.
 418
 419        This limit can be configured with the `AbstractMotor.set_current_limit` method."""
 420        ...
 421
 422    def voltage_limit(self) -> float:
 423        """Returns the voltage limit for the motor if one has been explicitly set."""
 424        ...
 425
 426    def temperature(self) -> float:
 427        """Returns the internal temperature recorded by the motor in increments of 5 °C."""
 428        ...
 429
 430    def set_profiled_velocity(self, rpm: int):
 431        """Changes the output velocity for a profiled movement (motor_move_absolute or
 432        motor_move_relative).
 433
 434        This will have no effect if the motor is not following a profiled movement.
 435
 436        Args:
 437
 438        - rpm: The new profiled velocity target in rotations per minute.
 439        """
 440        ...
 441
 442    def reset_position(self):
 443        """Sets the current encoder position to zero without moving the motor.
 444
 445        Analogous to taring or resetting the encoder to the current position.
 446        """
 447        ...
 448
 449    def set_current_limit(self, amps: float):
 450        """Sets the current limit for the motor in amps.
 451
 452        Args:
 453
 454        - amps: The new current limit in amps.
 455        """
 456        ...
 457
 458    def set_voltage_limit(self, volts: float):
 459        """Sets the voltage limit for the motor in volts.
 460
 461        Args:
 462
 463        - volts: The new voltage limit in volts.
 464        """
 465        ...
 466
 467    def is_over_temperature(self) -> bool:
 468        """Returns `True` if the motor's over temperature flag is set."""
 469        ...
 470
 471    def is_over_current(self):
 472        """Returns `True` if the motor's over-current flag is set."""
 473        ...
 474
 475    def is_driver_fault(self):
 476        """Returns `True` if a H-bridge (motor driver) fault has occurred."""
 477        ...
 478
 479    def is_driver_over_current(self):
 480        """Returns `True` if the motor's H-bridge has an over-current fault."""
 481        ...
 482
 483    def status(self) -> int:
 484        """Returns the status flags of a motor as bits."""
 485        ...
 486
 487    def faults(self) -> int:
 488        """Returns the fault flags of the motor as bits."""
 489        ...
 490
 491    def motor_type(self):
 492        """Returns the type of the motor.
 493
 494        This does not check the hardware, it simply returns the type that the motor was created
 495        with."""
 496        ...
 497
 498    def position(self, unit: RotationUnit) -> float:
 499        """Returns the angular position of the motor as measured by the IME (integrated motor encoder).
 500
 501        This is returned as a floating-point number in the given `RotationUnit`.
 502
 503        # Gearing affects position!
 504
 505        Position measurements are dependent on the Motor's `Gearset`, and may be reported
 506        incorrectly if the motor is configured with the incorrect gearset variant. Make sure
 507        that the motor is configured with the same gearset as its physical cartridge color.
 508
 509        Args:
 510
 511        - unit: The unit in which to return the position.
 512        """
 513        ...
 514
 515    def set_position(self, position: float, position_unit: RotationUnit):
 516        """Sets the current encoder position to the given position without moving the motor.
 517
 518        Analogous to taring or resetting the encoder so that the new position is equal to the given
 519        position.
 520
 521        Args:
 522
 523        - position: The position to set the encoder to.
 524        - position_unit: The unit of the given position.
 525        """
 526        ...
 527
 528    def set_direction(self, direction: Direction):
 529        """Sets the motor to operate in a given `Direction`.
 530
 531        This determines which way the motor considers to be “forwards”. You can use the marking on
 532        the back of the motor as a reference:
 533
 534        - When `Direction.FORWARD` is specified, positive velocity/voltage values will cause the
 535          motor to rotate **with the arrow on the back**. Position will increase as the motor
 536          rotates **with the arrow**.
 537        - When `Direction.REVERSE` is specified, positive velocity/voltage values will cause the
 538          motor to rotate **against the arrow on the back**. Position will increase as the motor
 539          rotates **against the arrow**.
 540
 541        Args:
 542
 543        - direction: The direction to set the motor to.
 544        """
 545        ...
 546
 547    def direction(self):
 548        """Returns the `Direction` of this motor."""
 549        ...
 550
 551
 552class V5Motor(AbstractMotor):
 553    """Represents an 11W (V5) Smart Motor. See `AbstractMotor`."""
 554
 555    MAX_VOLTAGE: Literal[12] = 12
 556    """The maximum voltage value that can be sent to a `V5Motor`."""
 557
 558    def __init__(self, port: int, direction: Direction, gearset: Gearset):
 559        """Creates a new 11W (V5) Smart Motor.
 560
 561        See `ExpMotor.__init__` to create a 5.5W (EXP) Smart Motor.
 562
 563        Args:
 564
 565        - port: The smart port to initialize the motor on.
 566        - direction: The direction to set the motor to.
 567        - gearset: The gearset to set the motor to.
 568        """
 569        ...
 570
 571    def set_gearset(self, gearset: Gearset):
 572        """Sets the gearset of an 11W motor.
 573
 574        This may silently fail if the motor is a 5.5W motor, which occurs in the edge
 575        case described in `V5Motor.gearset`.
 576
 577        Args:
 578
 579        - gearset: the new `Gearset` to use for the motor.
 580        """
 581        ...
 582
 583    def gearset(self) -> Gearset:
 584        """Returns the gearset of an 11W motor.
 585
 586        For 5.5W motors [1], this will always be returned as `Gearset.GREEN`.
 587
 588        [1] There is a slim edge case in which you initialize a `V5Motor` at a time
 589        when the specified port indeed has a plugged-in 11W motor, but then unplug
 590        it and replace it with a 5.5W motor. Note that the respective constructors of
 591        `V5Motor` and `ExpMotor` *will* throw if the motor is not the correct type.
 592        """
 593        ...
 594
 595
 596class ExpMotor(AbstractMotor):
 597    """Represents an 5.5W (EXP) Smart Motor. See `AbstractMotor`."""
 598
 599    def __init__(self, port: int, direction: Direction):
 600        """Creates a new 5.5W (EXP) Smart Motor.
 601
 602        See `V5Motor.__init__` to create a 11W (V5) Smart Motor.
 603
 604        Args:
 605
 606        - port: The smart port to initialize the motor on.
 607        - direction: The direction to set the motor to.
 608        """
 609        ...
 610
 611    MAX_VOLTAGE: Literal[8] = 8
 612    """The maximum voltage value that can be sent to a `ExpMotor`."""
 613
 614
 615class DistanceObject:
 616    """Readings from a physical object detected by a Distance Sensor."""
 617
 618    distance: int
 619    "The distance of the object from the sensor (in millimeters)."
 620
 621    confidence: float
 622    """The confidence in the distance measurement from 0.0 to 1.0."""
 623
 624    velocity: float
 625    """Observed velocity of the object in m/s."""
 626
 627    relative_size: int
 628    """A guess at the object's "relative size".
 629
 630    This is a value that has a range of 0 to 400. A 18" x 30" grey card will return a value of
 631    approximately 75 in typical room lighting. If the sensor is not able to detect an object,
 632    None is returned.
 633
 634    This sensor reading is unusual, as it is entirely unitless with the seemingly arbitrary
 635    range of 0-400 existing due to VEXCode's
 636    [`vex::sizeType`](https://api.vex.com/v5/home/python/Enums.html#object-size-types) enum
 637    having four variants. It's unknown what the sensor is *actually* measuring here either,
 638    so use this data with a grain of salt."""
 639
 640
 641class DistanceSensor:
 642    """A distance sensor plugged into a Smart Port.
 643
 644    The VEX V5 Distance Sensor uses a
 645    Class 1 laser to measure the distance, object size classification, and relative velocity of a
 646    single object.
 647
 648    # Hardware Overview
 649
 650    The sensor uses a narrow-beam Class 1 laser (similar to phone proximity sensors) for precise
 651    detection. It measures distances from 20mm to 2000mm with varying accuracy (±15mm below 200mm,
 652    ±5% above 200mm).
 653
 654    The sensor can classify detected objects by relative size, helping distinguish between walls and
 655    field elements. It also measures the relative approach velocity between the sensor and target.
 656
 657    Due to the use of a laser, measurements are single-point and highly directional, meaning that
 658    objects will only be detected when they are directly in front of the sensor's field of view.
 659
 660    Like all other Smart devices, VEXos will process sensor updates every 10mS.
 661    """
 662
 663    def __init__(self, port: int):
 664        """Creates a new distance sensor given the port.
 665
 666        Args:
 667
 668        - port: The port number of the sensor.
 669        """
 670        ...
 671
 672    def object(self) -> Union[DistanceObject, None]:
 673        """Attempts to detect an object, returning `None` if no object could be found."""
 674        ...
 675
 676    def status(self) -> int:
 677        """Returns the internal status code of the distance sensor.
 678
 679        The status code of the signature can tell you if the sensor is still initializing or if it
 680        is working correctly.
 681
 682        - If the distance sensor is still initializing, the status code will be 0x00.
 683        - If it is done initializing and functioning correctly, the status code will be 0x82 or
 684          0x86.
 685        """
 686        ...
 687
 688
 689class AiVisionColor:
 690    """A color signature used by an AI Vision Sensor to detect color blobs."""
 691
 692    r: int
 693    """The red component of the RGB color value."""
 694
 695    g: int
 696    """The green component of the RGB color value."""
 697
 698    b: int
 699    """The blue component of the RGB color value."""
 700
 701    hue_range: float
 702    """The accepted hue range of the color. VEXcode limits this value to [0, 20]"""
 703
 704    saturation_range: float
 705    """The accepted saturation range of the color."""
 706
 707    def __init__(
 708        self, r: int, g: int, b: int, hue_range: float, saturation_range: float
 709    ):
 710        """Creates a new `AiVisionColor` from the provided args.
 711
 712        Args:
 713
 714        - r: The red component of the RGB color value.
 715        - g: The green component of the RGB color value.
 716        - b: The blue component of the RGB color value.
 717        - hue_range: The accepted hue range of the color.
 718        - saturation_range: The accepted saturation range of the color.
 719        """
 720        ...
 721
 722
 723class AiVisionColorCode:
 724    """A color code used by an AI Vision Sensor to detect groups of color blobs.
 725
 726    Color codes are effectively "groups" of color signatures. A color code associated multiple color
 727    signatures on the sensor will be detected as a single object when all signatures are seen next
 728    to each other.
 729
 730    Color codes can associate up to 7 color signatures and detections will be returned as
 731    `AiVisionObject.Code` variants.
 732    """
 733
 734    def __init__(
 735        self,
 736        first: Union[int, None],
 737        second: Union[int, None],
 738        third: Union[int, None],
 739        fourth: Union[int, None],
 740        fifth: Union[int, None],
 741        sixth: Union[int, None],
 742        seventh: Union[int, None],
 743    ):
 744        """Creates a new `AiVisionColorCode` from the provided args.
 745
 746        Args:
 747
 748        - first: the first color signature id.
 749        - second: the second color signature id.
 750        - third: the third color signature id.
 751        - fourth: the fourth color signature id.
 752        - fifth: the fifth color signature id.
 753        - sixth: the sixth color signature id.
 754        - seventh: the seventh color signature id.
 755        """
 756        ...
 757
 758    # we annotate the docstring as @public because pdoc otherqise doesn't
 759    # document slot items
 760    def __getitem__(self, item: int):
 761        """@public Returns the color signature id at the given index.
 762
 763        Note that this does NOT support setting. For example, the following code works:
 764        ```python
 765        color_code_ids = [1, 2, 3, 4, 5, 6, 7]
 766        my_color_code = AiVisionColorCode(*color_code_ids)
 767        print(my_color_code[2]) # prints 3
 768        ```
 769        But this code doesn't:
 770        ```python
 771        color_code_ids = [1, 2, 3, 4, 5, 6, 7]
 772        my_color_code = AiVisionColorCode(*color_code_ids)
 773        my_color_code[6] = 9 # fails
 774        ```
 775        """
 776        ...
 777
 778
 779class AiVisionDetectionMode:
 780    """Flags relating to the sensor's detection mode."""
 781
 782    APRILTAG: ClassVar["AiVisionDetectionMode"]
 783    """Enable apriltag detection"""
 784
 785    COLOR: ClassVar["AiVisionDetectionMode"]
 786    """Enable color detection"""
 787
 788    MODEL: ClassVar["AiVisionDetectionMode"]
 789    """Enable model detection"""
 790
 791    COLOR_MERGE: ClassVar["AiVisionDetectionMode"]
 792    """Merge color blobs?"""
 793
 794    def __or__(self, value) -> AiVisionDetectionMode:
 795        """@public Bitwise OR is applied to the internal bitflags, "merging" the modes. The result is returned
 796
 797        ```python
 798        sensor = AiVisionSensor(7)
 799        # enable apriltag and color detection
 800        sensor.set_detection_mode(AiVisionDetectionMode.APRILTAG | AiVisionDetectionMode.COLOR)
 801        ```
 802        """
 803        ...
 804
 805    def __ior__(self, value):
 806        """@public Bitwise OR is applied to the internal bitflags, "merging" the modes. `self` is set to the result.
 807
 808        ```python
 809        sensor = AiVisionSensor(7)
 810        # enable apriltag and color detection
 811        mode = AiVisionDetectionMode.APRILTAG
 812        mode |= AiVisionDetectionMode.COLOR
 813        sensor.set_detection_mode(mode)
 814        ```
 815        """
 816        ...
 817
 818
 819AiVisionDetectionMode.APRILTAG = AiVisionDetectionMode()
 820AiVisionDetectionMode.COLOR = AiVisionDetectionMode()
 821AiVisionDetectionMode.MODEL = AiVisionDetectionMode()
 822AiVisionDetectionMode.COLOR_MERGE = AiVisionDetectionMode()
 823
 824
 825class AiVisionFlags:
 826    """Represents the mode of the AI Vision sensor."""
 827
 828    DISABLE_APRILTAG: ClassVar["AiVisionFlags"]
 829    """Disable apriltag detection"""
 830
 831    DISABLE_COLOR: ClassVar["AiVisionFlags"]
 832    """Disable color detection"""
 833
 834    DISABLE_MODEL: ClassVar["AiVisionFlags"]
 835    """Disable model detection"""
 836
 837    COLOR_MERGE: ClassVar["AiVisionFlags"]
 838    """Merge color blobs?"""
 839
 840    DISABLE_STATUS_OVERLAY: ClassVar["AiVisionFlags"]
 841    """Disable status overlay"""
 842
 843    DISABLE_USB_OVERLAY: ClassVar["AiVisionFlags"]
 844    """Disable USB overlay"""
 845
 846    def __or__(self, value) -> AiVisionDetectionMode:
 847        """@public Bitwise OR is applied to the internal bitflags, "merging" the modes. The result is returned
 848
 849        ```python
 850        sensor = AiVisionSensor(7)
 851        # disable status and usb overlays
 852        sensor.set_flags(AiVisionFlags.DISABLE_STATUS_OVERLAY | AiVisionFlags.DISABLE_USB_OVERLAY)
 853        ```
 854        """
 855        ...
 856
 857    def __ior__(self, value):
 858        """@public Bitwise OR is applied to the internal bitflags, "merging" the modes. `self` is set to the result.
 859
 860        ```python
 861        sensor = AiVisionSensor(7)
 862        # disable status and usb overlays
 863        mode = AiVisionFlags.DISABLE_STATUS_OVERLAY
 864        mode |= AiVisionFlags.DISABLE_USB_OVERLAY
 865        sensor.set_flags(mode)
 866        ```
 867        """
 868        ...
 869
 870
 871AiVisionFlags.DISABLE_APRILTAG = AiVisionFlags()
 872AiVisionFlags.DISABLE_COLOR = AiVisionFlags()
 873AiVisionFlags.DISABLE_MODEL = AiVisionFlags()
 874AiVisionFlags.COLOR_MERGE = AiVisionFlags()
 875AiVisionFlags.DISABLE_STATUS_OVERLAY = AiVisionFlags()
 876AiVisionFlags.DISABLE_USB_OVERLAY = AiVisionFlags()
 877
 878
 879class AiVisionColorObject:
 880    """The data associated with an AI Vision object detected by color blob detection."""
 881
 882    id: int
 883    """ID of the signature used to detect this object."""
 884
 885    position_x: int
 886    """The x component of the top-left corner of the object."""
 887
 888    position_y: int
 889    """The y component of the top-left corner of the object."""
 890
 891    width: int
 892    """The width of the object."""
 893
 894    height: int
 895    """The height of the object."""
 896
 897
 898class AiVisionCodeObject:
 899    """The data associated with an AI Vision object detected by color code detection."""
 900
 901    id: int
 902    """ID of the code used to detect this object."""
 903
 904    position_x: int
 905    """The x component of the position of the object."""
 906
 907    position_y: int
 908    """The y component of the position of the object."""
 909
 910    width: int
 911    """The width of the object."""
 912
 913    height: int
 914    """The height of the object."""
 915
 916    def angle(self, unit: RotationUnit) -> float:
 917        """The angle of the object's associated colors. Not always reliably available.
 918
 919        Args:
 920
 921        - units: The unit of measurement for the angle. This is the unit of
 922        the returned `float`.
 923        """
 924        ...
 925
 926
 927class AiVisionAprilTagObject:
 928    """The data associated with an AI Vision object detected by apriltag detection."""
 929
 930    id: int
 931    """The detected AprilTag(s) ID number"""
 932
 933    top_left_x: int
 934    """x component of the position of the top-left corner of the tag"""
 935
 936    top_left_y: int
 937    """y component of the position of the top-left corner of the tag"""
 938
 939    top_right_x: int
 940    """x component of the position of the top-right corner of the tag"""
 941
 942    top_right_y: int
 943    """y component of the position of the top-right corner of the tag"""
 944
 945    bottom_left_x: int
 946    """x component of the position of the bottom-left corner of the tag"""
 947
 948    bottom_left_y: int
 949    """y component of the position of the bottom-left corner of the tag"""
 950
 951    bottom_right_x: int
 952    """x component of the position of the bottom-right corner of the tag"""
 953
 954    bottom_right_y: int
 955    """y component of the position of the bottom-right corner of the tag"""
 956
 957
 958class AiVisionModelObject:
 959    """The data associated with an AI Vision object detected by an onboard model."""
 960
 961    id: int
 962    """ID of the detected object."""
 963
 964    position_x: int
 965    """The x component of the position of the object."""
 966
 967    position_y: int
 968    """The y component of the position of the object."""
 969
 970    width: int
 971    """The width of the object."""
 972
 973    height: int
 974    """The height of the object."""
 975
 976    confidence: int
 977    """The confidence reported by the model."""
 978
 979    classification: str
 980    """A string describing the specific onboard model used to detect this object."""
 981
 982
 983class AprilTagFamily:
 984    """Possible april tag families to be detected by the `AiVisionSensor`."""
 985
 986    CIRCLE21H7: ClassVar["AprilTagFamily"]
 987    """Circle21h7 family"""
 988
 989    TAG16H5: ClassVar["AprilTagFamily"]
 990    """16h5 family"""
 991
 992    TAG36H11: ClassVar["AprilTagFamily"]
 993    """36h11 family"""
 994
 995    TAG25H9: ClassVar["AprilTagFamily"]
 996    """25h9 family"""
 997
 998
 999AprilTagFamily.TAG36H11 = AprilTagFamily()
1000AprilTagFamily.TAG25H9 = AprilTagFamily()
1001AprilTagFamily.TAG16H5 = AprilTagFamily()
1002AprilTagFamily.CIRCLE21H7 = AprilTagFamily()
1003
1004
1005class AiVisionSensor:
1006    """An AI Vision sensor.
1007
1008    The AI Vision sensor is
1009    meant to be a direct upgrade from the Vision Sensor with a wider camera range
1010    and AI model capabilities.
1011
1012    # Hardware overview
1013
1014    The AI Vision sensor has three detection modes that can all be enabled at the same time:
1015    - [Color detection](AiVisionDetectionMode::COLOR)
1016    - [Custom model detection](AiVisionDetectionMode::MODEL)
1017    - [AprilTag detection](AiVisionDetectionMode::APRILTAG) (requires color detection to be enabled)
1018
1019    Currently there is no known way to upload custom models to the sensor and fields do not have
1020    AprilTags. However, there are built-in models that can be used for detection.
1021
1022    See [VEX's documentation](https://kb.vex.com/hc/en-us/articles/30326315023892-Using-AI-Classifications-with-the-AI-Vision-Sensor) for more information.
1023
1024    The resolution of the AI Vision sensor is 320x240 pixels. It has a horizontal FOV of 74 degrees
1025    and a vertical FOV of 63 degrees. Both of these values are a slight upgrade from the Vision
1026    Sensor.
1027
1028    Unlike the Vision Sensor, the AI Vision sensor uses more human-readable color signatures that
1029    may be created without the AI Vision utility, though uploading color signatures with VEX's AI
1030    Vision Utility over USB is still an option.
1031    """
1032
1033    MAX_OBJECTS: int = 24
1034    """Maximum number of objects that can be detected at once."""
1035
1036    HORIZONTAL_RESOLUTION: int = 320
1037    """The horizontal resolution of the AI Vision sensor."""
1038
1039    VERTICAL_RESOLUTION: int = 240
1040    """The vertical resolution of the AI Vision sensor."""
1041
1042    HORIZONTAL_FOV: float = 74.0
1043    """The horizontal FOV of the vision sensor in degrees."""
1044
1045    VERTICAL_FOV: float = 63.0
1046    """The vertical FOV of the vision sensor in degrees."""
1047
1048    DIAGONAL_FOV: float = 87.0
1049    """The diagonal FOV of the vision sensor in degrees."""
1050
1051    def temperature(self) -> float:
1052        """Returns the current temperature of the sensor in degrees Celsius."""
1053        ...
1054
1055    def set_color_code(self, id: int, code: AiVisionColorCode):
1056        """
1057        Registers a color code association on the sensor.
1058
1059        Color codes are effectively "groups" of color signatures. A color code associated multiple
1060        color signatures on the sensor will be detected as a single object when all signatures are
1061        seen next to each other.
1062
1063        Args:
1064
1065        - id: The ID of the color code to register. Must be in [1, 8].
1066        - code: The `AiVisionColorCode` to register.
1067        """
1068
1069    def color_code(self, id: int) -> Union[AiVisionColorCode, None]:
1070        """Returns the color code set on the AI Vision sensor with the given ID if it exists.
1071
1072        Args:
1073
1074        - id: The ID of the color code to retrieve. Must be in [1, 8].
1075
1076        Returns:
1077
1078        - The color code associated with the given ID if it exists, or None if no color code is set.
1079        """
1080        ...
1081
1082    def color_codes(self) -> List[Union[AiVisionColorCode, None]]:
1083        """Returns all color codes set on the AI Vision sensor as a list of 8 optional `AiVisionColorCode` objects."""
1084        ...
1085
1086    def set_color(self, id: int, color: AiVisionColor) -> AiVisionColor:
1087        """Sets a color signature for the AI Vision sensor.
1088
1089        Args:
1090
1091        - id: The ID of the color signature to register. Must be in [1, 7].
1092        - color: The `AiVisionColor` to register.
1093        """
1094        ...
1095
1096    def color(self, id: int) -> Union[AiVisionColor, None]:
1097        """Returns the color signature set on the AI Vision sensor with the given ID if it exists.
1098
1099        Args:
1100
1101        - id: The ID of the color signature to retrieve. Must be in [1, 7].
1102        """
1103        ...
1104
1105    def colors(self) -> List[Union[AiVisionColor, None]]:
1106        """Returns all color signatures set on the AI Vision sensor as a list of 7 optional `AiVisionColor` objects."""
1107        ...
1108
1109    def set_detection_mode(self, mode: AiVisionDetectionMode):
1110        """Sets the detection mode of the AI Vision sensor.
1111
1112        Args:
1113
1114        - mode: The new `AiVisionDetectionMode` to set.
1115        """
1116        ...
1117
1118    def flags(self) -> AiVisionFlags:
1119        """Returns the current flags of the AI Vision sensor including the detection mode flags set by `AiVisionSensor.set_detection_mode`."""
1120        ...
1121
1122    def set_flags(self, mode: AiVisionFlags):
1123        """Set the full flags of the AI Vision sensor, including the detection mode.
1124
1125        Args:
1126
1127        - mode: The new `AiVisionFlags` to set.
1128        """
1129        ...
1130
1131    def start_awb(self):
1132        """Restarts the automatic white balance process."""
1133        ...
1134
1135    def enable_test(self, test: int):
1136        """Unknown use.
1137
1138        Args:
1139
1140        - test: unknown purpose.
1141        """
1142        ...
1143
1144    def set_apriltag_family(self, family: AprilTagFamily):
1145        """Sets the AprilTag family that the sensor will try to detect.
1146
1147        Args:
1148
1149        - family: The `AprilTagFamily` for the sensor to try to detect.
1150        """
1151        ...
1152
1153    def object_count(self) -> int:
1154        """Returns the number of objects currently detected by the AI Vision sensor."""
1155        ...
1156
1157    def objects(
1158        self,
1159    ) -> List[
1160        Union[
1161            AiVisionColorObject,
1162            AiVisionCodeObject,
1163            AiVisionModelObject,
1164            AiVisionAprilTagObject,
1165        ]
1166    ]:
1167        """Returns all objects detected by the AI Vision sensor."""
1168        ...
1169
1170
1171# TODOs:
1172# * controller
1173# * vasyncio
1174# * competition runtime