SerialWombatCharlieplex.h

Go to the documentation of this file.

#pragma once
/*
Copyright 2026 Broadwell Consulting Inc.
 
"Serial Wombat" is a registered trademark of Broadwell Consulting Inc. in
the United States.  See SerialWombat.com for usage guidance.
 
Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
*/
 
#include <stdint.h>
#include "SerialWombat.h"


class SerialWombatCharlieplex : public SerialWombatPin, public SerialWombatAbstractScaledOutput
{
public:
    enum displayMode_t
    {
        DISPLAY_MODE_BITMAP = 0,              
        DISPLAY_MODE_PUBLIC_DATA_BITMAP = 1,  
        DISPLAY_MODE_SCALED_SINGLE_LED = 2,   
        DISPLAY_MODE_SCALED_BARGRAPH = 3      
    };
 
    static const uint8_t MAX_PINS = 8;
    static const uint8_t MAX_LEDS = 56;
    static const uint8_t BITMAP_BYTES = 7;
    static const uint8_t UNUSED_PIN = 0xFF;
    static const uint8_t UNUSED_LED = 0xFF;

    SerialWombatCharlieplex(SerialWombatChip& serialWombat) :
        SerialWombatPin(serialWombat),
        SerialWombatAbstractScaledOutput(serialWombat)
    {
    }

    int16_t begin(uint8_t pin0,
        uint8_t pin1,
        uint8_t pin2,
        uint8_t pin3,
        uint8_t pin4,
        uint8_t pin5 = UNUSED_PIN,
        uint8_t pin6 = UNUSED_PIN,
        uint8_t pin7 = UNUSED_PIN,
        displayMode_t displayMode = DISPLAY_MODE_BITMAP,
        uint8_t scanPeriod_mS = 0)
    {
        const uint8_t pins[MAX_PINS] = {
            pin0,
            pin1,
            pin2,
            pin3,
            pin4,
            pin5,
            pin6,
            pin7
        };
 
        uint8_t numberOfPins = MAX_PINS;
        for (uint8_t i = 0; i < MAX_PINS; ++i)
        {
            if (pins[i] == UNUSED_PIN)
            {
                numberOfPins = i;
                break;
            }
        }
 
        _pin = pin0;
        _pinMode = (uint8_t)PIN_MODE_CHARLIEPLEX;
 
        uint8_t tx0[] = {
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE0,
            _pin,
            _pinMode,
            numberOfPins,
            (uint8_t)displayMode,
            scanPeriod_mS,
            pin1,
            pin2
        };
 
        int16_t result = _sw.sendPacket(tx0);
        if (result < 0)
        {
            return result;
        }
 
        uint8_t tx1[] = {
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE1,
            _pin,
            _pinMode,
            pin3,
            pin4,
            pin5,
            pin6,
            pin7
        };
 
        return _sw.sendPacket(tx1);
    }

    int16_t writeLEDArray(const uint8_t ledArray[BITMAP_BYTES])
    {
        uint8_t tx2[] = {
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE2,
            _pin,
            _pinMode,
            ledArray[0],
            ledArray[1],
            ledArray[2],
            ledArray[3],
            ledArray[4]
        };
 
        int16_t result = _sw.sendPacket(tx2);
        if (result < 0)
        {
            return result;
        }
 
        uint8_t tx3[] = {
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE3,
            _pin,
            _pinMode,
            ledArray[5],
            ledArray[6],
            0x55,
            0x55,
            0x55
        };
 
        return _sw.sendPacket(tx3);
    }

    int16_t setLEDs(uint8_t led0,
        uint8_t led1 = UNUSED_LED,
        uint8_t led2 = UNUSED_LED,
        uint8_t led3 = UNUSED_LED,
        uint8_t led4 = UNUSED_LED)
    {
        return writeLEDCommand(
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE5,
            led0, led1, led2, led3, led4);
    }

    int16_t setLEDs(const uint8_t ledIndexes[], uint8_t count)
    {
        return writeLEDCommand(
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE5,
            ledIndexes,
            count);
    }

    int16_t clearLEDs(uint8_t led0,
        uint8_t led1 = UNUSED_LED,
        uint8_t led2 = UNUSED_LED,
        uint8_t led3 = UNUSED_LED,
        uint8_t led4 = UNUSED_LED)
    {
        return writeLEDCommand(
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE6,
            led0, led1, led2, led3, led4);
    }

    int16_t clearLEDs(const uint8_t ledIndexes[], uint8_t count)
    {
        return writeLEDCommand(
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE6,
            ledIndexes,
            count);
    }

    int16_t clearLEDs()
    {
        uint8_t ledArray[BITMAP_BYTES] = {0, 0, 0, 0, 0, 0, 0};
        return writeLEDArray(ledArray);
    }

    int16_t writeLookupEntries(uint8_t firstLEDIndex,
        uint8_t entry0,
        uint8_t entry1,
        uint8_t entry2,
        uint8_t entry3)
    {
        uint8_t tx[] = {
            (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE4,
            _pin,
            _pinMode,
            firstLEDIndex,
            entry0,
            entry1,
            entry2,
            entry3
        };
        return _sw.sendPacket(tx);
    }

    int16_t writeLookupTable(const uint8_t lookupTable[MAX_LEDS])
    {
        for (uint8_t firstLEDIndex = 0;
            firstLEDIndex < MAX_LEDS;
            firstLEDIndex += 4)
        {
            int16_t result = writeLookupEntries(
                firstLEDIndex,
                lookupTable[firstLEDIndex],
                lookupTable[firstLEDIndex + 1],
                lookupTable[firstLEDIndex + 2],
                lookupTable[firstLEDIndex + 3]);
 
            if (result < 0)
            {
                return result;
            }
        }
        return 0;
    }

    static uint8_t encodePinPair(uint8_t highPinIndex, uint8_t lowPinIndex)
    {
        return (uint8_t)((highPinIndex << 4) | (lowPinIndex & 0x0F));
    }

    uint8_t pin()
    {
        return SerialWombatPin::_pin;
    }

    uint8_t swPinModeNumber()
    {
        return SerialWombatPin::_pinMode;
    }
 
private:
    int16_t writeLEDCommand(uint8_t command,
        uint8_t led0,
        uint8_t led1,
        uint8_t led2,
        uint8_t led3,
        uint8_t led4)
    {
        const uint8_t ledIndexes[5] = {led0, led1, led2, led3, led4};
 
        for (uint8_t i = 0; i < 5; ++i)
        {
            if (ledIndexes[i] != UNUSED_LED && ledIndexes[i] >= MAX_LEDS)
            {
                return -1;
            }
        }
 
        uint8_t tx[] = {
            command,
            _pin,
            _pinMode,
            led0,
            led1,
            led2,
            led3,
            led4
        };
 
        return _sw.sendPacket(tx);
    }
 
    int16_t writeLEDCommand(uint8_t command,
        const uint8_t ledIndexes[],
        uint8_t count)
    {
        if (count > 5)
        {
            return -1;
        }
 
        uint8_t leds[5] = {
            UNUSED_LED,
            UNUSED_LED,
            UNUSED_LED,
            UNUSED_LED,
            UNUSED_LED
        };
 
        for (uint8_t i = 0; i < count; ++i)
        {
            if (ledIndexes[i] >= MAX_LEDS)
            {
                return -1;
            }
            leds[i] = ledIndexes[i];
        }
 
        return writeLEDCommand(
            command,
            leds[0],
            leds[1],
            leds[2],
            leds[3],
            leds[4]);
    }
 
};