io.silverspoon.bulldog.core.gpio

Class Pin

java.lang.Object

io.silverspoon.bulldog.core.gpio.Pin

public class Pin
extends Object

A pin in libbulldog is solely a management container. It contains features that can be activated on it.

E.g. one might choose to use the Pin as a DigitalOutput or a DigitalInput.

The pin contains the necessary information to be set up according to the user's wishes. If the information of this class is not enough, then board implementations derive from it. It ensures that only one feature can be activated at a time. If asynchronous or blocking operations are currently in progress on another feature, then the pin will deny any other feature activation during that time.

Mostly, the pin is just used to grab a feature that is available on it:
DigitalOutput output = pin.as(DigitalOutput.class);
Pwm pwm = pin.as(Pwm.class);

Constructor Summary

Constructors

Constructor and Description
Pin(String name, int address, String port, int indexOnPort) Instantiates a new pin.

Method Summary

Methods

Modifier and Type	Method and Description
<T extends PinFeature> void	activateFeature(Class<T> feature) Activates a feature on a pin.
Pin	addFeature(PinFeature feature) Adds the feature to the pin.
void	addFeatureActivationListener(FeatureActivationListener listener) Adds a feature activation listener.
<T extends PinFeature> T	as(Class<T> feature) This is a very important method.
void	block(PinFeature blocker) Blocks a pin.
void	clearFeatureActivationListeners() Clears the list of feature activation listeners.
protected void	fireFeatureActivated(PinFeature feature) This method fires the feature activated event.
protected void	fireFeatureActivating(PinFeature feature) This method fires the feature activating event.
protected void	fireFeatureDeactivated(PinFeature feature) This method fires the feature deactivated event.
protected void	fireFeatureDeactivating(PinFeature feature) This method fires the feature deactivating event.
PinFeature	getActiveFeature() Gets the active feature.
int	getAddress() Gets the address of the pin.
String	getAlias() Gets the alias of the pin.
PinFeature	getBlocker() Gets the pin feature that currently blocks the pin.
<T extends PinFeature> T	getFeature(Class<T> featureClass) Grabs a feature from the pin, if it is available.
List<FeatureActivationListener>	getFeatureActivationListeners() Gets a list of all registered FeatureActivationListeners.
List<PinFeature>	getFeatures() Gets a list of all available feature instances.
int	getIndexOnPort() Gets the index of the pin on the port.
String	getName() Gets the name of the pin.
String	getPort() Gets the port of the pin.
boolean	hasFeature(Class<? extends PinFeature> featureClass) Checks if a feature class is available on a pin.
boolean	isBlocked() Checks if the pin is currently blocked by a feature.
boolean	isFeatureActive(Class<? extends PinFeature> featureClass) Checks if a feature class is currently active on this pin.
boolean	isFeatureActive(PinFeature feature) Checks if the feature instance is currently active on this pin.
Pin	removeFeature(Class<? extends PinFeature> featureClass) Removes a feature from a pin.
void	removeFeatureActivationListener(FeatureActivationListener listener) Removes a feature activation listener.
void	setAlias(String alias) Sets the alias of the pin.
void	unblock(PinFeature blocker) Unblocks a pin if it is currently blocked.

Methods inherited from class java.lang.Object

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

Constructor Detail

Pin

public Pin(String name,
   int address,
   String port,
   int indexOnPort)

Instantiates a new pin.

Parameters:

name - the name of the pin

address - the address of the pin

port - the port of the pin

indexOnPort - the index of the pin on the port

Method Detail

activateFeature

public <T extends PinFeature> void activateFeature(Class<T> feature)

Activates a feature on a pin.

Type Parameters:

T - the type (classname) of the desired feature

Parameters:

feature - the type (classname) of the desired feature

addFeature

public Pin addFeature(PinFeature feature)

Adds the feature to the pin. This method is used to provide a pin instance with all the features that it is capable of.

Parameters:

feature - the instance of the feature to be added

Returns:

the pin for a fluent style API

removeFeature

public Pin removeFeature(Class<? extends PinFeature> featureClass)

Removes a feature from a pin. More precisely, it removes the first occurrence of a feature class from the pin.

Parameters:

featureClass - the feature class to be removed

Returns:

the pin for a fluent style API

as

public <T extends PinFeature> T as(Class<T> feature)

This is a very important method. It is the standard way to configure a pin for usage with a desired feature (e.g. PWM, DigitalIO).

Type Parameters:

T - the concrete type of the pin feature.

Parameters:

feature - the classname of the feature.

Returns:

the the concrete type of the pin feature.

block

public void block(PinFeature blocker)

Blocks a pin. While a pin is blocked, not other pin feature can be activated on the pin until it unblocks the pin. See unblock.

Parameters:

blocker - the pin feature that should block the pin.

unblock

public void unblock(PinFeature blocker)

Unblocks a pin if it is currently blocked.

Parameters:

blocker - the feature that currently blocks the pin. If the pin is blocked, but not by the pin feature given in the argument, then a PinBlockedException will be thrown.

getBlocker

public PinFeature getBlocker()

Gets the pin feature that currently blocks the pin.

Returns:

the pin feature that currently blocks the pin.

isBlocked

public boolean isBlocked()

Checks if the pin is currently blocked by a feature.

Returns:

true, if is blocked

getFeature

public <T extends PinFeature> T getFeature(Class<T> featureClass)

Grabs a feature from the pin, if it is available. First, the method will look for a pin feature class that exactly matches the class specified in the argument. If that cannot be found, it returns a pin feature that is at least assignable from the desired feature class.

Type Parameters:

T - the concrete type of the pin feature

Parameters:

featureClass - the class of the pin feature

Returns:

the feature if it was found or null otherwise.

getActiveFeature

public PinFeature getActiveFeature()

Gets the active feature.

Returns:

the feature that is currently active on this pin.

isFeatureActive

public boolean isFeatureActive(Class<? extends PinFeature> featureClass)

Checks if a feature class is currently active on this pin.

Parameters:

featureClass - the feature class

Returns:

true, if the feature class is active on the pin

isFeatureActive

public boolean isFeatureActive(PinFeature feature)

Checks if the feature instance is currently active on this pin.

Parameters:

feature - the feature

Returns:

true, if the feature instance is currently active on the pin.

getAddress

public int getAddress()

Gets the address of the pin. Usually this corresponds with the GPIO pin number of the package or board.

Returns:

the address

getPort

public String getPort()

Gets the port of the pin.

Returns:

the port

getIndexOnPort

public int getIndexOnPort()

Gets the index of the pin on the port.

Returns:

the index of the pin on the port.

getFeatures

public List<PinFeature> getFeatures()

Gets a list of all available feature instances.

Returns:

all feature instances of this pin.

getName

public String getName()

Gets the name of the pin. Usually a combination of port name and pin index.

Returns:

the name of the pin.

getAlias

public String getAlias()

Gets the alias of the pin. The alias is an alternate name that can be set by the user. setAlias.

Returns:

the alias of the pin.

setAlias

public void setAlias(String alias)

Sets the alias of the pin. This is an alternate name that can be set by the user.

Parameters:

alias - the alternate name of the pin.

hasFeature

public boolean hasFeature(Class<? extends PinFeature> featureClass)

Checks if a feature class is available on a pin.

Parameters:

featureClass - the feature class

Returns:

true, if the feature class is available on the pin, false otherwise.

addFeatureActivationListener

public void addFeatureActivationListener(FeatureActivationListener listener)

Adds a feature activation listener.

Parameters:

listener - the listener

removeFeatureActivationListener

public void removeFeatureActivationListener(FeatureActivationListener listener)

Removes a feature activation listener.

Parameters:

listener - the listener

clearFeatureActivationListeners

public void clearFeatureActivationListeners()

Clears the list of feature activation listeners.

getFeatureActivationListeners

public List<FeatureActivationListener> getFeatureActivationListeners()

Gets a list of all registered FeatureActivationListeners.

Returns:

a list containing all registered FeatureActivationListeners

fireFeatureActivating

protected void fireFeatureActivating(PinFeature feature)

This method fires the feature activating event. It denotes that a feature activation has begun. the feature is not ready for use yet. All registered FeatureActivationListeners will react on it.

Parameters:

feature - the feature that is currently being activated

fireFeatureActivated

protected void fireFeatureActivated(PinFeature feature)

This method fires the feature activated event. It denotes that a feature has been fully activated and is ready for use. All registered FeatureActivationListeners will react on it.

Parameters:

feature - the feature that is currently being activated

fireFeatureDeactivating

protected void fireFeatureDeactivating(PinFeature feature)

This method fires the feature deactivating event. It denotes that a feature deactivation has begun. the feature is not torn down yet. All registered FeatureActivationListeners will react on it.

Parameters:

feature - the feature that is currently being activated

fireFeatureDeactivated

protected void fireFeatureDeactivated(PinFeature feature)

This method fires the feature deactivated event. It denotes that a feature deactivation has finished. the feature is completely torn down. All registered FeatureActivationListeners will react on it.

Parameters:

feature - the feature that is currently being activated