Ctrl+K

EVNAlpha

EVNAlpha#

EVNAlpha is a class used to interface with the onboard hardware on EVN Alpha:

  • Button

  • LED

  • I2C Multiplexers

  • Battery ADC

Some Technical Details#

EVNAlpha uses hardware interrupts for the onboard button to act as an toggle switch (default) or pushbutton. This approach allows other libraries to use the values read by EVNButton, without the user having to poll and work around blocking functions.

By default, the button output is also linked to 2 other functions. Both can disabled by the user if needed:

  • Motor Operation: the button can act as a motor disable switch, so that users can pause their robot before uploading

  • LED: the LED acts as an indicator for the button output

EVN Alpha has 2 TCA9548A I2C multiplexers, 1 on each I2C bus. This allows users to connect multiple I2C devices with the same I2C address without worrying about address clashing. However, users must set the port (1-16) for a given peripheral before communicating with it. EVNAlpha includes functions for port selection and de-selection to ease this process.

Note

Our EVN-specific peripheral libaries (e.g. EVNColourSensor) do the port selection automatically, so port selection functions are not needed for them.

Note

For Ports 9-16, 3rd party libraries and end-user code have to use Wire1 to interface with their sensors, as these ports are connected to the I2C1 bus.

class EVNAlpha(uint8_t mode = BUTTON_TOGGLE, bool link_led = true, bool link_movement = false, bool button_invert = false, uint32_t i2c_freq = 100000)#
Parameters

  • mode –

    Determines behaviour of buttonRead(). Defaults to BUTTON_TOGGLE

    • BUTTON_TOGGLE – Returns false on startup and toggles between true and false with each button press

    • BUTTON_PUSHBUTTON – Returns true only when button is pressed

    • BUTTON_DISABLE – Always returns true

  • link_led – Links LED to display buttonRead() output. Defaults to true.

  • link_movement – Links all motor and servo operation to buttonRead() output. Defaults to false.

  • button_invert – Inverts output of buttonRead(). Defaults to false.

  • i2c_freq – I2C frequency in Hz. Defaults to 400000 (400kHz).

//constructor with default options
EVNAlpha board;

//constructor if you wish to set non-default options
EVNAlpha board(BUTTON_PUSHBUTTON, false, false, false, 400000);

Functions#

void begin()

Initializes on-board hardware. This function should be called at the start of void setup(), before anything else.

EVNAlpha board;

void setup()
{
    board.begin();
}

Note

EVNAlpha should only be initialized on the main core using void setup(). Its functions should only be called on the main core as well (in void setup() or void loop()).

LED / Button#

bool buttonRead()

Get button output (varies depending on mode parameter in class constructor)

Returns

boolean signifying button output

bool button_output = board.buttonRead();
void ledWrite(bool state)

Set LED to turn on (true) or off (false). However, the LED state can be overridden by the battery reading functions (see below).

Parameters

state – state to write to LED

board.ledWrite(true);  //LED on
board.ledWrite(false); //LED off

I2C Port Control#

These functions will be used mainly if you are trying to operate third-party I2C devices, that aren’t Standard Peripherals.

void setPort(uint8_t port)
Parameters

port – I2C port to be enabled (1-16)

//set I2C port 16 to be active
board.setPort(16);
uint8_t getPort()
Returns

last I2C port called using setPort() (1-16)

int port = board.getPort(); //returns 1 on startup
uint8_t getWirePort()
Returns

last Wire I2C port called using setPort() (1-8)

int wport = board.getWirePort();    //returns 1 on startup
uint8_t getWire1Port()
Returns

last Wire1 I2C port called using setPort() (9-16)

int w1port = board.getWire1Port();  //returns 9 on startup
void printPorts()

This is an I2C port scanner function which prints all I2C devices on every port using Serial

board.printPorts();

Example Serial Monitor Output:

EVN Alpha I2C Port Scanner
Battery: 8.183V | Cell 1: 4.096V | Cell 2: 4.087
Port 16: 0x6A

Even though no peripherals are connected to the board, port 16 has one I2C device under address 0x6A, which is our onboard battery charger and voltage measurement device.

Battery Voltage Reading#

All battery voltage reading functions have a flash_when_low input. This is a low battery alert function, which flashes the LED at a rate of 5Hz (5 blinks per second) when the battery voltage is too low.

When the alert is on, the LED’s previous output (whether linked to button or controlled by the user) will be overridden. To add the alert to your code, add getBatteryVoltage() (or getCell1Voltage() and getCell2Voltage()) to void loop() and they will check the voltage each loop.

void loop()
{
  //main code here

  board.getBatteryVoltage(); //battery alert!
}
int16_t getBatteryVoltage(bool flash_when_low = true, uint16_t low_threshold_mv = 6900)
Parameters

  • flash_when_low – Sets LED to flash when battery voltage falls below low_threshold_mv. Defaults to true

  • low_threshold_mv – Battery voltage threshold (in millivolts). When battery voltage falls below this voltage and flash_when_low is true, low voltage alert is triggered. Defaults to 6900.

Returns

combined voltage of both battery cells in millivolts

int battery = board.getBatteryVoltage();
int16_t getCell1Voltage(bool flash_when_low = true, uint16_t low_threshold_mv = 3450)

Cell 1 refers to the cell nearer to the edge of the board.

Parameters

  • flash_when_low – Sets LED to flash when battery voltage falls below low_threshold_mv. Defaults to true

  • low_threshold_mv – Cell voltage threshold (in millivolts). When this cell’s voltage falls below this threshold and flash_when_low is true, low battery alert is triggered. Defaults to 3450.

Returns

voltage of first cell in millivolts

int cell1 = board.getCell1Voltage();
int16_t getCell2Voltage(bool flash_when_low = true, uint16_t low_threshold_mv = 3450)

Cell 2 refers to the cell nearer to the centre of the board.

Parameters

  • flash_when_low – Sets LED to flash when battery voltage falls below low_threshold_mv. Defaults to true

  • low_threshold_mv – Cell voltage threshold (in millivolts). When this cell’s voltage falls below this threshold and flash_when_low is true, the low battery alert is triggered. Defaults to 3450.

Returns

voltage of second cell in millivolts

int cell2 = board.getCell2Voltage();

Set Functions#

void setMode(uint8_t mode)
Parameters

mode – Determines behaviour of buttonRead() (options shown below)

  • BUTTON_TOGGLE

  • BUTTON_PUSHBUTTON

  • BUTTON_DISABLE

board.setMode(BUTTON_TOGGLE);
void setLinkLED(bool enable)
Parameters

enable – Links LED to display buttonRead() output

board.setLinkLED(true);
void setLinkMovement(bool enable)
Parameters

enable – Links all motor and servo operation to buttonRead() output

board.setLinkMovement(true);
void setButtonInvert(bool enable)
Parameters

enable – Inverts output of buttonRead()

board.setButtonInvert(true);

Get Functions#

uint8_t getMode()

This function returns the button mode in numbers, as shown below.

The written button modes (e.g. BUTTON_TOGGLE, BUTTON_PUSHBUTTON) are converted to these numbers when compiled, so statements like if (board.getMode() == BUTTON_TOGGLE) {} are valid.

Returns

Mode of button in numerical form

  • 0 (BUTTON_DISABLE)

  • 1 (BUTTON_TOGGLE)

  • 2 (BUTTON_PUSHBUTTON)

if (board.getMode() == BUTTON_TOGGLE)
{

}
bool getLinkLED()
Returns

Whether LED is linked to buttonRead() output

bool link_led = board.getLinkLED();
bool getLinkMovement()
Returns

Whether motor and servo operation is linked to buttonRead() output

bool link_movement = board.getLinkLED();
bool getButtonInvert()
Returns

Whether output of buttonRead() is inverted

bool button_invert = board.getButtonInvert();
Contents