Derived Components: A layer above components.

[trickeydan]

Introduction

I've been considering how we should implement Ultrasound sensor support, which is an interesting problem, as mentioned previously in #66.

I propose implementing a sort-of layer that sits above Components in our abstraction, I have deemed these to be 'Meta-Components' 'Derived Components'.

A meta-component derived component is simply a component that is defined by the user, rather than the API author. At first this may sound like it doesn't work with our current intentions for how students will use the API, but I think this makes a lot of sense.

I think the easiest way to do this is with a few code examples.

Example 1: A fixed Ultrasound sensor on a robot / board.

Robot class

class Robot(BaseRobot):

    def __init__(self) -> None:
        self.rx_pin = GPIOPin(0, backend, supported_modes=[GPIOPinMode.Ultrasound])
        self.tx_pin = GPIOPin(1, backend, supported_modes=[GPIOPinMode.Ultrasound])
        self.front_ultrasound = Ultrasound(self.rx_pin, self.tx_pin)     

Student Code

r = Robot()
print(r.front_ultrasound.get_distance())

Example 2: Ultrasound wired to GPIO with fw support

Robot class

class Robot(BaseRobot):

    def __init__(self) -> None:
        self.rx_pin = GPIOPin(0, backend, supported_modes=[GPIOPinMode.Ultrasound])
        self.tx_pin = GPIOPin(1, backend, supported_modes=[GPIOPinMode.Ultrasound])

Student Code

r = Robot()
front_ultrasound = Ultrasound(r.rx_pin, r.tx_pin)     
print(front_ultrasound.get_distance())

This will obviously require a new Component and Interface to be defined, but note in particular how this "Meta-Component" 'derived component' does not take a Backend as a parameter in it's constructor, instead taking GPIOPins and using their Backend.

[kierdavis]

I like this.

This easily opens the door to allowing the user to use any two pins for an ultrasound sensor e.g.

API vendor:

class Robot:
  def __init__(self) -> None:
    self.gpio_pins = [GPIOPin(n, backend, supported_modes=[GPIOPinMode.Ultrasound]) for n in range(14)]

User:

r = Robot()
my_sensor_1 = Ultrasound(r.gpio_pins[3], r.gpio_pins[4])
my_sensor_2 = Ultrasound(r.gpio_pins[10], r.gpio_pins[13])
print(my_sensor_1.read_distance())

Note that the user doesn't have to construct meta-components directly; they could be hidden behind the API in the same way that normal components are:

API vendor

class Robot:
  ...
  def get_ultrasound_sensor(self, trigger_pin_number, echo_pin_number):
    return Ultrasound(self.gpio_pins[trigger_pin_number], self.gpio_pins[echo_pin_number])

User:

r = Robot()
print(r.get_ultrasound_sensor(3, 4).read_distance())

Note that I haven't considered the boundary between the j5 codebase and the competition vendor's codebase in the above examples

[kierdavis]

I do have a nitpick about the name: "meta-component" sounds like something that describes a component, like how a Python metaclass describes a class or how metadata in general describes some distinct but related data. How about something like "composite component" or "derived component", that indicates that it's a component built from other components?

[trickeydan]

From what I've been able to determine, this does not require any additional base classes, it is instead a design pattern that we should use. I shall write some docs on this in order to finish this off.