Custom Hardware Extensions - addonovan/ftc-ext GitHub Wiki

Hardware Extensions

A hardware extension is just that, an extension of a previous hardware device. This can be done to add more (or any) helpful methods, or to provide new functionalities that would've been difficult to create before.

Quick look

A valid hardware extension:

• has the HardwareExtension annotation
  • has a valid class as the value to its hardwareMapType
• Inherits from HardwareDevice in some way, shape, or form.
• Has a valid constructor
  • required first parameter has the same type as described by hardwareMapType
  • optional second parameter is a String

Custom HardwareExtensions are accessed the same way as standard ones, no additional set up needed.

Setup

There are some requirements for a new hardware extension, and, although not rigorous, if they are not met, then the API throws some mean error messages which may dishearten you and make you want to just give up. This guide is here to protect you from that! :^)

HardwareExtension annotation

In order for a class to be recognized as a hardware extension is must have the @HardwareExtension annotation attached to its header. The HardwareExtension annotation also requires a HardwareDevice class as a value for its hardwareMapType parameter. The hardwareMapType must be a class or interface that would be able to be directly pulled from a device mapping in the hardware map (i.e. DcMotor is fine because hardwareMap.dcMotor.get( ... ) returns a DcMotor). If this is not done properly, when the getDevice method attempts to create the hardware extension, it will throw an IllegalAnnotationValueException, informing you that you have to choose a correct value for hardwareMapType.

Inheritance

Hardware extensions must inherit from the HardwareDevice interface supplied by Qualcomm. This can be attained by either directly implementing it (ew) or extending something (usually the hardwareMapType's class) that does.

Constructor

Hardware extensions require a public constructor, which must meet the following requirements, else the API can't actually instantiate the extension (which makes it mad).
The first parameter is required, this parameter must be of the same type that hardwareMapType in the annotation is. When created by the API, this parameter will be filled by the actual device that it's wrapping around.
The second parameter is optional, this parameter must be a string, and when created by the API, is the name of the hardware device in the hardware map. This is mostly used for writing debug messages.

Only one constructor is required, but having both constructors is fine. When the API instantiated the extension, if there are two valid constructors, it will always use the one that also supplies the name.

Examples

Java

@HardwareExtension( hardwareMapType = DcMotor.class )
public class MyHardwareExtension extends DcMotor
{
   public MyHardwareExtension( DcMotor dcMotor )
   {
      super( dcMotor.controller, dcMotor.port );
   }
   // or
   public MyHardwareExtension( DcMotor dcMotor, String name )
   {
      super( dcMotor.controller, dcMotor.port );
      // do whatever you'd like with 'name'
   }
}

Kotlin

@HardwareExtension( DcMotor::class )
class MyHardwareExtension( dcMotor: DcMotor ) : DcMotor( dcMotor.controller, dcMotor.port )
{
    ...
}
// or
@HardwareExtension( DcMotor::class )
class MyHardwareExtension( dcMotor: DcMotor, name: String ) : DcMotor( dcMotor.controller, dcMotor.port )
{
     // do whatever with 'name'
     ...
}

Access

So you've set up your hardware extension, now you want to use it? It's actually really simple, just use it like you see in [this](Advanced Hardware) page, all the extensions are handled on-the-fly individually, so there's no registration anywhere else.