Package com.crossbotics.ftchelper.robot

Class PieceSensor

java.lang.Object
com.crossbotics.ftchelper.robot.Module<PieceSensor>
com.crossbotics.ftchelper.robot.PieceSensor
All Implemented Interfaces:
Subsystem
public final class PieceSensor extends Module<PieceSensor>
A sensor that looks at ONE spot (the intake's mouth, or the "ready to fire" slot) and says which game piece is there: one of your kinds ("POLLEN"), Pieces.UNKNOWN (a piece, but not one it knows), or Pieces.NONE. 

 readyColor = add(PieceSensor.color("ready_color").kinds("POLLEN", "RED_NECTAR", "BLUE_NECTAR"));   // Robot.java
 if (robot.readyColor.sees("POLLEN")) ...

Three kinds of sensor:

  • color(java.lang.String) a REV Color Sensor V3 (REV-31-1557): its colour tells the kinds apart, its distance says whether a piece is there (1-10 cm).
  • distance a distance sensor (REV 2m Distance Sensor, REV-31-1505) looking ACROSS a channel: a bigger piece comes closer, so it tells SIZES apart (not colours).
  • camera(java.lang.String) a second webcam looking at the spot, with the SDK's PredominantColorProcessor (the main colour inside a box of the picture): colours, no distance.

Tunables (the section is the device name in CamelCase: "ready_color" reads Tunables.ReadyColor): one number per kind, named like the kind: its colour (hue, 0-360 degrees) for a colour sensor or a camera, its distance reading (mm) for a distance sensor. Find them with the Piece Tuner (PieceTunerOpMode). Also nearMm (a piece is there when the distance is below it), hueTolerance / sizeToleranceMm (how far from a kind's number still counts), minSaturation (camera: how colourful the box must be), steadyMs (a reading must stay this long before it counts), gapMm (colour and distance sensors: two touching pieces count as two when the distance rises and falls again by this much).

Never waits: a REV 2m Distance Sensor is read on a helper thread (one reading can take up to 0.2 s), a camera's answer is the SDK's latest. A reading older than 0.25 s is thrown away; with no new reading for 0.5 s (a sensor unplugged, a camera that stopped) it sees nothing and warns. A sensor missing from the robot configuration warns at INIT and sees nothing: the OpMode still runs. Docs: docs/modules/robot.md (section "Pieces and PieceSensor")

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addTelemetry(RobotTelemetry t)
    The part's telemetry line; each module adds its own.
    int
    arrivals()
    How many separate pieces it has seen arrive (a new piece, a different kind right behind, a distance dip).
    PieceSensor
    box(double left, double top, double right, double bottom)
    Camera only: the box of the picture to read, from the centre: -1 = left/bottom edge, 1 = right/top edge.
    static PieceSensor
    camera(String webcamName)
    A second webcam that looks at the spot from close by (the SDK's PredominantColorProcessor reads the main colour in a box of the picture).
    static PieceSensor
    color(String name)
    A colour sensor with a distance reading, like the REV Color Sensor V3 (configure it as "REV Color Sensor V3").
    static PieceSensor
    distance(String name)
    A distance sensor looking across a channel at the far wall (REV 2m Distance Sensor: configure it as "REV 2M Distance Sensor").
    double
    distanceMm()
    The latest distance in mm (NaN for a camera, or no reading yet).
    boolean
    hasDistance()
    True for a sensor that knows how far away the piece is (colour and distance sensors).
    double
    hueDeg()
    The latest colour, 0-360 degrees (NaN for a distance sensor, or no reading yet).
    boolean
    isWorking()
    True while it has a recent reading (within 0.5 s).
    String
    kind()
    What is at the spot now: a kind, Pieces.UNKNOWN, or Pieces.NONE.
    List<String>
    kindNames()
    The kinds it tells apart.
    PieceSensor
    kinds(String... names)
    The kinds of piece it can tell apart, as names that are also the Tunables fields (letters, digits and _ only), e.g.
    double
    measured()
    The number this sensor compares: hue (colour, camera) or distance in mm (distance sensor).
    boolean
    measuresSize()
    True for a distance sensor (it compares mm, not colours).
    String
    problem()
    Why it sees nothing ("" when it works): a sensor or camera that is missing, did not start, or stopped answering.
    String
    rawKind()
    The latest reading's kind, before the steadyMs wait (the tuner shows it).
    int
    readings()
    How many fresh readings it has had (the Piece Tuner counts only new ones).
    double
    saturation()
    The latest colourfulness, 0 (grey) to 1 (pure colour); NaN for a distance sensor.
    boolean
    sees(String kind)
    True if a piece of this kind is at the spot now.
    boolean
    seesPiece()
    True if any piece (known or not) is at the spot now.
    String
    sensorType()
    "color", "distance" or "camera".
    void
    stop()
    Stops all motion.
    void
    update()
    Every loop: picks up the newest reading (a colour sensor: a few ms over I2C; a distance sensor or a camera: never waits) and works out what is there.

    Methods inherited from class com.crossbotics.ftchelper.robot.Module

    deviceName, isOptional, isPresent, looks, name, optional, part, tunables, zone, zoneAbove, zoneBelow

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • color

      public static PieceSensor color(String name)
      A colour sensor with a distance reading, like the REV Color Sensor V3 (configure it as "REV Color Sensor V3"). Put it 1-2 cm from where a piece passes or rests.
      Parameters:
      name - its configuration name, e.g. "ready_color"

    • distance

      public static PieceSensor distance(String name)
      A distance sensor looking across a channel at the far wall (REV 2m Distance Sensor: configure it as "REV 2M Distance Sensor"). A bigger piece is closer: it tells pieces apart by SIZE only. The 2m sensor reads from 5 cm: put it at least 5 cm from the nearest side of the biggest piece.
      Parameters:
      name - its configuration name, e.g. "intake_distance"

    • camera

      public static PieceSensor camera(String webcamName)
      A second webcam that looks at the spot from close by (the SDK's PredominantColorProcessor reads the main colour in a box of the picture). It runs alongside an AprilTag webcam or a Limelight; it uses a small picture (320x240) and no live view, to leave USB room for the other camera.
      Parameters:
      webcamName - its configuration name, e.g. "Webcam 2"

    • kinds

      public PieceSensor kinds(String... names)
      The kinds of piece it can tell apart, as names that are also the Tunables fields (letters, digits and _ only), e.g. "POLLEN", "RED_NECTAR". Inside Pieces it gets the Pieces' kinds.
      Parameters:
      names - one or more names

    • box

      public PieceSensor box(double left, double top, double right, double bottom)
      Camera only: the box of the picture to read, from the centre: -1 = left/bottom edge, 1 = right/top edge. Default: the middle quarter (-0.25, 0.25, 0.25, -0.25).

    • kindNames

      public List<String> kindNames()
      The kinds it tells apart.

    • update

      public void update()
      Every loop: picks up the newest reading (a colour sensor: a few ms over I2C; a distance sensor or a camera: never waits) and works out what is there.

    • kind

      public String kind()
      What is at the spot now: a kind, Pieces.UNKNOWN, or Pieces.NONE. Steady: a reading counts after steadyMs. NONE while it has no recent reading (see isWorking()).

    • sees

      public boolean sees(String kind)
      True if a piece of this kind is at the spot now.

    • seesPiece

      public boolean seesPiece()
      True if any piece (known or not) is at the spot now.

    • rawKind

      public String rawKind()
      The latest reading's kind, before the steadyMs wait (the tuner shows it). NONE with no recent reading.

    • isWorking

      public boolean isWorking()
      True while it has a recent reading (within 0.5 s). False before the first one, and when the sensor is missing, unplugged, or a camera stopped sending pictures: then it sees NONE and Pieces does not count with it.

    • arrivals

      public int arrivals()
      How many separate pieces it has seen arrive (a new piece, a different kind right behind, a distance dip).

    • readings

      public int readings()
      How many fresh readings it has had (the Piece Tuner counts only new ones).

    • hueDeg

      public double hueDeg()
      The latest colour, 0-360 degrees (NaN for a distance sensor, or no reading yet).

    • saturation

      public double saturation()
      The latest colourfulness, 0 (grey) to 1 (pure colour); NaN for a distance sensor.

    • distanceMm

      public double distanceMm()
      The latest distance in mm (NaN for a camera, or no reading yet).

    • measured

      public double measured()
      The number this sensor compares: hue (colour, camera) or distance in mm (distance sensor).

    • measuresSize

      public boolean measuresSize()
      True for a distance sensor (it compares mm, not colours).

    • hasDistance

      public boolean hasDistance()
      True for a sensor that knows how far away the piece is (colour and distance sensors).

    • problem

      public String problem()
      Why it sees nothing ("" when it works): a sensor or camera that is missing, did not start, or stopped answering.

    • sensorType

      public String sensorType()
      "color", "distance" or "camera".

    • stop

      public void stop()
      Description copied from interface: Subsystem
      Stops all motion. Called at the end of every OpMode.

    • addTelemetry

      public void addTelemetry(RobotTelemetry t)
      Description copied from class: Module
      The part's telemetry line; each module adds its own.
      Specified by:
      addTelemetry in interface Subsystem
      Overrides:
      addTelemetry in class Module<PieceSensor>