Serial Wombat Arduino Library
Public Member Functions | Public Attributes | List of all members
SerialWombat Class Reference

#include <SerialWombat.h>

Public Member Functions

 SerialWombat ()
 
void begin (HardwareSerial &serial)
 initialize a Serial Wombat chip to use a Serial Interface. More...
 
void begin (HardwareSerial &serial, bool reset)
 initialize a Serial Wombat chip to use a Serial Interface. More...
 
void begin (TwoWire &wire, uint8_t i2cAddress)
 initialize a Serial Wombat chip to use a specified I2C Interface and address. More...
 
void begin (uint8_t i2cAddress)
 initialize a Serial Wombat chip to use the default Wire I2C Interface and specified address. More...
 
void begin (TwoWire &wire, uint8_t i2cAddress, bool reset)
 initialize a Serial Wombat chip to use a specified I2C Interface and address. More...
 
 ~SerialWombat ()
 
int sendPacket (uint8_t tx[], uint8_t rx[])
 Send an 8 byte packet to the Serial Wombat chip and wait for 8 bytes back. More...
 
int sendPacket (uint8_t tx[])
 Send an 8 byte packet to the Serial Wombat chip. More...
 
char * readVersion (void)
 Request version string (combined model and firmware) and return pointer to it. More...
 
uint16_t readPublicData (uint8_t pin)
 Read the 16 Bit public data associated with a Serial Wombat Pin Mode. More...
 
uint16_t writePublicData (uint8_t pin, uint16_t value)
 Write a 16 bit value to a Serial Wombat pin Mode. More...
 
uint16_t readSupplyVoltage_mV (void)
 Measure the Serial Wombat chip's Supply voltage. More...
 
void hardwareReset ()
 Send a reset command to the Serial Wombat chip. More...
 
void pinMode (uint8_t pin, uint8_t mode)
 Set a pin to INPUT or OUTPUT. More...
 
void pinMode (uint8_t pin, uint8_t mode, bool pullDown, bool openDrain)
 Set a pin to INPUT or OUTPUT, with options for pull Ups and open Drain settings. More...
 
void digitalWrite (uint8_t pin, uint8_t val)
 Set an output pin High or Low. More...
 
int digitalRead (uint8_t pin)
 Reads the state of a Pin. More...
 
int analogRead (uint8_t pin)
 Configures pin as analog input and does an immediate A/D conversion.
More...
 
void analogWrite (uint8_t pin, int val)
 Set a pin to PWM output. More...
 
bool queryVersion ()
 Send a version request to the Serial Wombat chip. More...
 
uint32_t readFramesExecuted ()
 Get the number of 1mS frames that have been executed since Serial Wombat chip reset. More...
 
uint16_t readOverflowFrames ()
 Get the number of times an overflow Frame has occured. More...
 
void jumpToBoot ()
 Jump to Bootloader and wait for a UART download of new firmware. More...
 
uint8_t readRamAddress (uint16_t address)
 Read Address from RAM based on 16 bit address. More...
 
void writeRamAddress (uint16_t address, uint8_t value)
 Write byte to Address in RAM based on 16 bit address. More...
 
uint32_t readFlashAddress (uint32_t address)
 Read Address from Flash based on 32 bit address. More...
 
void sleep ()
 Shuts down most functions of the Serial Wombat chip reducing power consumption. More...
 
void wake ()
 Called to send a dummy packet to the Serial Wombat chip to wake it from sleep and ready it for other commands. More...
 

Public Attributes

uint16_t _supplyVoltagemV = 0
 
uint8_t model [4] = { 0 }
 Contains the last model retreived by queryVersion() as a zero-terminated string. More...
 
uint8_t fwVersion [4] = { 0 }
 Contains the last firmware Version retreived by queryVersion() as a zero-terminated string. More...
 
uint8_t uniqueIdentifier [16]
 
uint8_t uniqueIdentifierLength = 0
 
uint16_t deviceIdentifier
 
uint16_t deviceRevision
 
uint32_t errorCount = 0
 Incremented every time a communication or command error is detected. More...
 
uint32_t errorNum = 0
 The last error number reported. More...
 

Detailed Description

/brief Class for a Serial Wombat chip. Each Serial Wombat chip on a project should have its own instance.

This class describes the capabilties of a Serial Wombat Chip that are not Pin Mode functionalities

Constructor & Destructor Documentation

◆ SerialWombat()

SerialWombat::SerialWombat ( )

◆ ~SerialWombat()

SerialWombat::~SerialWombat ( )

Member Function Documentation

◆ analogRead()

int SerialWombat::analogRead ( uint8_t  pin)

Configures pin as analog input and does an immediate A/D conversion.

This function is compatible with the Arduino Uno analogRead function.
It does not make use of advanced Serial Wombat chip's functionality such as averaging and filtering. Consider declaring a SerialWombatAnalogInput instead.

Parameters
pinThe Serial Wombat pin to set. Valid values for SW4A: 0-3 SW4B: 1-3
Returns
An Analog to Digital conversion ranging from 0 to 1023 (10-bit)

◆ analogWrite()

void SerialWombat::analogWrite ( uint8_t  pin,
int  val 
)

Set a pin to PWM output.

This function is compatible with the Arduino Uno analogWrite function, but will output a PWM with a different frequency. Consider declaring a SerialWombatPWM instead. It has higher resolution and the ability to choose frequency.

Parameters
pinThe Serial Wombat pin to set. Valid values for SW4A: 0-3 SW4B: 1-3
valA value from 0 (always low) to 255(always high) for the PWM duty cycle

◆ begin() [1/5]

void SerialWombat::begin ( HardwareSerial &  serial)

initialize a Serial Wombat chip to use a Serial Interface.

This call causes the Serial Wombat chip to be reset through its reset command as the first operation. The Serial Wombat chips's source voltage is then read as well as its version.

Parameters
serialSerial Interface to be used by the Serial Wombat library

◆ begin() [2/5]

void SerialWombat::begin ( HardwareSerial &  serial,
bool  reset 
)

initialize a Serial Wombat chip to use a Serial Interface.

The reset parameter determines if the Serial Wombat chip is reset prior to other initialization operations. If false, then any prior pin modes and configurations may still be in place. The Serial Wombat chips's source voltage is then read as well as its version.

Parameters
serialSerial Interface to be used by the Serial Wombat library
resetWhether or not to reset the Serial Wombat chip via command as the first initialization operation

◆ begin() [3/5]

void SerialWombat::begin ( TwoWire &  wire,
uint8_t  i2cAddress 
)

initialize a Serial Wombat chip to use a specified I2C Interface and address.

This call causes the Serial Wombat chip to be reset through its reset command as the first operation. The Serial Wombat chip's source voltage is then read as well as its version.

Parameters
wireI2C interface to be used by the Serial Wombat Library
i2cAddressI2C Follower address of the Serial Wombat chip commanded by this instance

◆ begin() [4/5]

void SerialWombat::begin ( TwoWire &  wire,
uint8_t  i2cAddress,
bool  reset 
)

initialize a Serial Wombat chip to use a specified I2C Interface and address.

This call causes the Serial Wombat chip to optionally reset through its reset command as the first operation. The Serial Wombat chip's source voltage is then read as well as its version.

Parameters
wireI2C interface to be used by the Serial Wombat Library
i2cAddressI2C Follower address of the Serial Wombat chip commanded by this instance
resetWhether or not to reset the Serial Wombat chip via command as the first initialization operation. If false, then any prior pin modes and configurations may still be in place.

◆ begin() [5/5]

void SerialWombat::begin ( uint8_t  i2cAddress)

initialize a Serial Wombat chip to use the default Wire I2C Interface and specified address.

This call causes the Serial Wombat chip to be reset through its reset command as the first operation. The Serial Wombat chip's source voltage is then read as well as its version.

Parameters
i2cAddressI2C Follower address of the Serial Wombat chip commanded by this instance

◆ digitalRead()

int SerialWombat::digitalRead ( uint8_t  pin)

Reads the state of a Pin.

Returns
Returns LOW if pin is low or public data is 0. Returns HIGH if pin is high or public data is > 0

◆ digitalWrite()

void SerialWombat::digitalWrite ( uint8_t  pin,
uint8_t  val 
)

Set an output pin High or Low.

Before calling this function, the pin should be configured as an input or output with pinMode()

Parameters
pinThe Serial Wombat pin to set. Valid values for SW4A: 0-3 SW4B: 1-3
valValid values are HIGH or LOW not use SW_INPUT, SW_HIGH or SW_LOW here, as these have different meanings

◆ hardwareReset()

void SerialWombat::hardwareReset ( )

Send a reset command to the Serial Wombat chip.

Sends a reset command to the Serial Wombat chip. The calling function should wait 500mS before sending additional commands.

◆ jumpToBoot()

void SerialWombat::jumpToBoot ( )

Jump to Bootloader and wait for a UART download of new firmware.

This function causes a reset of the Serial Wombat chip and causes it to remain in the bootloader until a power-cycle occurs. This allows loading new firmware via a UART connection to the bottom two pins (DIP pins 4 (RX) and 5(TX)) on the SW4A/SW4B. When jumping to boot the TX pin will go high. All other communication or functional pins will become inputs (i.e. PWMS, etc will stop).

◆ pinMode() [1/2]

void SerialWombat::pinMode ( uint8_t  pin,
uint8_t  mode 
)

Set a pin to INPUT or OUTPUT.

This method matches the Arduino Digital io pinMode command It should only be used on pins that have not been configured to a more sophisticated (e.g. debounce or servo) pin mode.

Parameters
pinThe Serial Wombat pin to set
modeValid values are INPUT or OUTPUT as defined by arduino. Do not use SW_INPUT, SW_HIGH or SW_LOW here, as these have different meanings

◆ pinMode() [2/2]

void SerialWombat::pinMode ( uint8_t  pin,
uint8_t  mode,
bool  pullDown,
bool  openDrain 
)

Set a pin to INPUT or OUTPUT, with options for pull Ups and open Drain settings.

Parameters
pinThe Serial Wombat pin to set
modeValid values are INPUT, OUTPUT or INPUT_PULLUP as defined by arduino. Do not use SW_INPUT, SW_HIGH or SW_LOW here, as these have different meanings
pullDownIf True, a weak pull down will be enabled on this pin (No effect on SW4A/SW4B)
openDrainIf True, output becomes openDrain output rather than push / pull

◆ queryVersion()

bool SerialWombat::queryVersion ( )

Send a version request to the Serial Wombat chip.

This function queries the Serial Wombat chip for its model and version and stores the result in the public members model and fwVersion as zero terminated strings. Returns true if the response is likely a proper version response and false otherwise.

Returns
TRUE if response was likely a valid version, FALSE otherwise

◆ readFlashAddress()

uint32_t SerialWombat::readFlashAddress ( uint32_t  address)

Read Address from Flash based on 32 bit address.

Most Arduino users should not need this command.

This command can be used to read flash locations within the Serial Wombat Chip

Addresses are not validated to be available in a given chip's address range.

Parameters
addressA 32-bit address pointing to a location in the Serial Wombat Chip's memory map
Returns
An 32 bit value returned from the Serial Wombat chip. 32 bits are used to accomodate different chips. The SW18 series has a 24 bit flash word, whereas the SW4A and SW4B have a 14 bit word.

◆ readFramesExecuted()

uint32_t SerialWombat::readFramesExecuted ( )

Get the number of 1mS frames that have been executed since Serial Wombat chip reset.

This value should be roughly equal to the mS since reset. It will vary based on the Serial Wombat chip's internal oscillator variation, and may run slow if Overflow frames are occuring.

◆ readOverflowFrames()

uint16_t SerialWombat::readOverflowFrames ( )

Get the number of times an overflow Frame has occured.

This value increments each time the Serial Wombat firmware determines it is time to start a new 1 mS frame, but the previous frame is still executing. Indicates processor loading over 100% of real-time. Overflows back to 0 when incremented from 65535.

◆ readPublicData()

uint16_t SerialWombat::readPublicData ( uint8_t  pin)

Read the 16 Bit public data associated with a Serial Wombat Pin Mode.

Reads and returns the 16 bit value associated with a Serial Wombat Pin Mode. Additionally, values of 65 and higher have special meanings. See Serial Wombat firmware documentation for details.

Returns
16 bit public data for pin specified
Parameters
pinThe pin (or special meaning value) for which to retreive data

◆ readRamAddress()

uint8_t SerialWombat::readRamAddress ( uint16_t  address)

Read Address from RAM based on 16 bit address.

Most Arduino users should not need this command.

This command can be used to read variables and registers within the Serial Wombat Chip Note that reading registers may have unintended side effects. See the microcontroller datasheet for details.

Note that Note that the PIC16F15214 used in the SW4A and SW4B chips is a Microchip Enhanced Mid-Range chip with both a banked RAM area and a Linear RAM area at an offset address. See the datasheet for details. It's wierd to people who are unfamilliar with it. The same location can have two different addresses.

Addresses are not validated to be available in a given chip's address range.

Parameters
addressA 16-bit address pointing to a location in the Serial Wombat Chip's memory map
Returns
An 8 bit value returned from the Serial Wombat chip.

◆ readSupplyVoltage_mV()

uint16_t SerialWombat::readSupplyVoltage_mV ( void  )

Measure the Serial Wombat chip's Supply voltage.

Causes the Serial Wombat chip to measure the counts for the internal 1.024V reference voltage. The Arduino library then converts these counts to a Source votlage in mV

Returns
The Serial Wombat chip's source voltage in mV

◆ readVersion()

char * SerialWombat::readVersion ( void  )

Request version string (combined model and firmware) and return pointer to it.

This queries the Serial Wombat chip for the 7 characters: product line (1 character) Model (3 characters) and firmware version (3 characters) This is stored in a string in the Serial Wombat object. A pointer to this string is returned.

◆ sendPacket() [1/2]

int SerialWombat::sendPacket ( uint8_t  tx[])

Send an 8 byte packet to the Serial Wombat chip.

This method sends 8 bytes via I2C and does not wait for a response. When sending to UART, the Library waits for an 8 byte response.

Parameters
txaddress of an array of 8 bytes to send
Returns
The number of bytes sent

◆ sendPacket() [2/2]

int SerialWombat::sendPacket ( uint8_t  tx[],
uint8_t  rx[] 
)

Send an 8 byte packet to the Serial Wombat chip and wait for 8 bytes back.

This method sends 8 bytes via I2C or Serial and blocks until 8 bytes are receieved back

Parameters
txaddress of an array of 8 bytes to send
rxaddress of an array of 8 bytes into which to put response.
Returns
The number of bytes received as a response, or a negative value if an error was returned from the Serial Wombat chip

◆ sleep()

void SerialWombat::sleep ( )

Shuts down most functions of the Serial Wombat chip reducing power consumption.

This command stops the Serial Wombat chip's internal clock, greatly reducing power consumption. The host is responsible for configuring outputs to a safe state prior to calling sleep.

Warning
This command does not cause any sort of shutdown routine to run. The chip just stops. \ Outputs, including PWM, Servo and Protected Outputs, may retain their logic levels \ at the moment the sleep command is processed. In other words, they may stay high or low as long as the chip is in sleep.

◆ wake()

void SerialWombat::wake ( )

Called to send a dummy packet to the Serial Wombat chip to wake it from sleep and ready it for other commands.

◆ writePublicData()

uint16_t SerialWombat::writePublicData ( uint8_t  pin,
uint16_t  value 
)

Write a 16 bit value to a Serial Wombat pin Mode.

Parameters
pinThe pin number to which to write
valueThe 16 bit value to write

◆ writeRamAddress()

void SerialWombat::writeRamAddress ( uint16_t  address,
uint8_t  value 
)

Write byte to Address in RAM based on 16 bit address.

Most Arduino users should not need this command.

This command can be used to write variables and registers within the Serial Wombat Chip Note that write registers may have unintended side effects. See the microcontroller datasheet for details.

Note that Note that the PIC16F15214 used in the SW4A and SW4B chips is a Microchip Enhanced Mid-Range chip with both a banked RAM area and a Linear RAM area at an offset address. See the datasheet for details. It's wierd to people who are unfamilliar with it. The same location can have two different addresses.

Addresses are not validated to be available in a given chip's address range.

Parameters
addressA 16-bit address pointing to a location in the Serial Wombat Chip's memory map
valueAn 8 bit value to be written to RAM

Member Data Documentation

◆ _supplyVoltagemV

uint16_t SerialWombat::_supplyVoltagemV = 0

Stores the last value retreived by readSupplyVoltage_mV(). Used by SerialWombatAnalogInput class to calculate mV outputs from retreived A/D counts. Don't access this member, as it may become private and SerialWombatAnalog input be made a friend of SerialWombat in the future. Call readSupplyVoltage_mV instead.

◆ deviceIdentifier

uint16_t SerialWombat::deviceIdentifier

◆ deviceRevision

uint16_t SerialWombat::deviceRevision

◆ errorCount

uint32_t SerialWombat::errorCount = 0

Incremented every time a communication or command error is detected.

◆ errorNum

uint32_t SerialWombat::errorNum = 0

The last error number reported.

◆ fwVersion

uint8_t SerialWombat::fwVersion[4] = { 0 }

Contains the last firmware Version retreived by queryVersion() as a zero-terminated string.

◆ model

uint8_t SerialWombat::model[4] = { 0 }

Contains the last model retreived by queryVersion() as a zero-terminated string.

◆ uniqueIdentifier

uint8_t SerialWombat::uniqueIdentifier[16]

◆ uniqueIdentifierLength

uint8_t SerialWombat::uniqueIdentifierLength = 0