microbit-dal/source/MicroBitDisplay.cpp

/**
  * Class definition for a MicroBitDisplay.
  *
  * A MicroBitDisplay represents the LED matrix array on the MicroBit device.
  */
#include "mbed.h"
#include "MicroBit.h"
#include "MicroBitMatrixMaps.h"
#include "nrf_gpio.h"

const int timings[MICROBIT_DISPLAY_GREYSCALE_BIT_DEPTH] = {1, 23, 70, 163, 351, 726, 1476, 2976};
MicroBitDisplay *MicroBitDisplay::defaultDisplay = NULL;

/**
  * Constructor.
  * Create a representation of a display of a given size.
  * The display is initially blank.
  *
  * @param x the width of the display in pixels.
  * @param y the height of the display in pixels.
  *
  * Example:
  * @code
  * MicroBitDisplay display(MICROBIT_ID_DISPLAY, 5, 5),
  * @endcode
  */
MicroBitDisplay::MicroBitDisplay(uint16_t id, uint8_t x, uint8_t y) :
    image(x*2,y)
{
    //set pins as output
    nrf_gpio_range_cfg_output(MICROBIT_DISPLAY_COLUMN_START,MICROBIT_DISPLAY_COLUMN_START + MICROBIT_DISPLAY_COLUMN_COUNT + MICROBIT_DISPLAY_ROW_COUNT);

    this->id = id;
    this->width = x;
    this->height = y;
    this->strobeRow = 0;
    this->strobeBitMsk = MICROBIT_DISPLAY_ROW_RESET;
    this->rotation = MICROBIT_DISPLAY_ROTATION_0;
    this->greyscaleBitMsk = 0x01;
    this->timingCount = 0;
    this->errorTimeout = 0;

    this->setBrightness(MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS);

    this->mode = DISPLAY_MODE_BLACK_AND_WHITE;
    this->animationMode = ANIMATION_MODE_NONE;

    this->lightSensor = NULL;

    if (!this->defaultDisplay)
        this->defaultDisplay = this;

	fiber_add_system_component(this);

    status |= MICROBIT_COMPONENT_RUNNING;
}

/**
  * Internal frame update method, used to strobe the display.
  *
  * TODO: Write a more efficient, complementary variation of this method for the case where
  * MICROBIT_DISPLAY_ROW_COUNT > MICROBIT_DISPLAY_COLUMN_COUNT.
  */
void MicroBitDisplay::systemTick()
{
    if(!(status & MICROBIT_COMPONENT_RUNNING))
        return;

    if(mode == DISPLAY_MODE_BLACK_AND_WHITE_LIGHT_SENSE)
    {
        renderWithLightSense();
        return;
    }

    // Move on to the next row.
    strobeBitMsk <<= 1;
    strobeRow++;

    //reset the row counts and bit mask when we have hit the max.
    if(strobeRow == MICROBIT_DISPLAY_ROW_COUNT){
        strobeRow = 0;
        strobeBitMsk = MICROBIT_DISPLAY_ROW_RESET;
    }

    if(mode == DISPLAY_MODE_BLACK_AND_WHITE)
        render();

    if(mode == DISPLAY_MODE_GREYSCALE)
    {
        greyscaleBitMsk = 0x01;
        timingCount = 0;
        renderGreyscale();
    }

    // Update text and image animations if we need to.
    this->animationUpdate();
}

void MicroBitDisplay::renderFinish()
{
    //kept inline to reduce overhead
    //clear the old bit pattern for this row.
    //clear port 0 4-7 and retain lower 4 bits
    nrf_gpio_port_write(NRF_GPIO_PORT_SELECT_PORT0, 0xF0 | (nrf_gpio_port_read(NRF_GPIO_PORT_SELECT_PORT0) & 0x0F));

    // clear port 1 8-12 for the current row
    nrf_gpio_port_write(NRF_GPIO_PORT_SELECT_PORT1, strobeBitMsk | 0x1F);
}

void MicroBitDisplay::render()
{
    // Simple optimisation. If display is at zero brightness, there's nothign to do.
    if(brightness == 0)
        return;

    int coldata = 0;

    // Calculate the bitpattern to write.
    for (int i = 0; i<MICROBIT_DISPLAY_COLUMN_COUNT; i++)
    {
        int x = matrixMap[i][strobeRow].x;
        int y = matrixMap[i][strobeRow].y;
        int t = x;

        if(rotation == MICROBIT_DISPLAY_ROTATION_90)
        {
                x = width - 1 - y;
                y = t;
        }

        if(rotation == MICROBIT_DISPLAY_ROTATION_180)
        {
                x = width - 1 - x;
                y = height - 1 - y;
        }

        if(rotation == MICROBIT_DISPLAY_ROTATION_270)
        {
                x = y;
                y = height - 1 - t;
        }

        if(image.getBitmap()[y*(width*2)+x])
            coldata |= (1 << i);
    }

    //write the new bit pattern
    //set port 0 4-7 and retain lower 4 bits
    nrf_gpio_port_write(NRF_GPIO_PORT_SELECT_PORT0, (~coldata<<4 & 0xF0) | (nrf_gpio_port_read(NRF_GPIO_PORT_SELECT_PORT0) & 0x0F));

    //set port 1 8-12 for the current row
    nrf_gpio_port_write(NRF_GPIO_PORT_SELECT_PORT1, strobeBitMsk | (~coldata>>4 & 0x1F));

    //timer does not have enough resolution for brightness of 1. 23.53 us
    if(brightness != MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS && brightness > MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS)
        renderTimer.attach_us(this, &MicroBitDisplay::renderFinish, (((brightness * 950) / (MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS)) * scheduler_get_tick_period()));

    //this will take around 23us to execute
    if(brightness <= MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS)
        renderFinish();
}

void MicroBitDisplay::renderWithLightSense()
{
    //reset the row counts and bit mask when we have hit the max.
    if(strobeRow == MICROBIT_DISPLAY_ROW_COUNT + 1)
    {

        MicroBitEvent(id, MICROBIT_DISPLAY_EVT_LIGHT_SENSE);

        strobeRow = 0;
        strobeBitMsk = MICROBIT_DISPLAY_ROW_RESET;
    }
    else
    {

        render();
        this->animationUpdate();

        // Move on to the next row.
        strobeBitMsk <<= 1;
        strobeRow++;
    }

}

void MicroBitDisplay::renderGreyscale()
{
    int coldata = 0;

    // Calculate the bitpattern to write.
    for (int i = 0; i<MICROBIT_DISPLAY_COLUMN_COUNT; i++)
    {
        int x = matrixMap[i][strobeRow].x;
        int y = matrixMap[i][strobeRow].y;
        int t = x;

        if(rotation == MICROBIT_DISPLAY_ROTATION_90)
        {
                x = width - 1 - y;
                y = t;
        }

        if(rotation == MICROBIT_DISPLAY_ROTATION_180)
        {
                x = width - 1 - x;
                y = height - 1 - y;
        }

        if(rotation == MICROBIT_DISPLAY_ROTATION_270)
        {
                x = y;
                y = height - 1 - t;
        }

        if(min(image.getBitmap()[y * (width * 2) + x],brightness) & greyscaleBitMsk)
            coldata |= (1 << i);
    }
    //write the new bit pattern
    //set port 0 4-7 and retain lower 4 bits
    nrf_gpio_port_write(NRF_GPIO_PORT_SELECT_PORT0, (~coldata<<4 & 0xF0) | (nrf_gpio_port_read(NRF_GPIO_PORT_SELECT_PORT0) & 0x0F));

    //set port 1 8-12 for the current row
    nrf_gpio_port_write(NRF_GPIO_PORT_SELECT_PORT1, strobeBitMsk | (~coldata>>4 & 0x1F));

    if(timingCount > MICROBIT_DISPLAY_GREYSCALE_BIT_DEPTH-1)
        return;

    greyscaleBitMsk <<= 1;

    if(timingCount < 3)
    {
        wait_us(timings[timingCount++]);
        renderGreyscale();
        return;
    }
    renderTimer.attach_us(this,&MicroBitDisplay::renderGreyscale, timings[timingCount++]);
}

/**
  * Periodic callback, that we use to perform any animations we have running.
  */
void
MicroBitDisplay::animationUpdate()
{
    // If there's no ongoing animation, then nothing to do.
    if (animationMode == ANIMATION_MODE_NONE)
        return;

    animationTick += FIBER_TICK_PERIOD_MS;

    if(animationTick >= animationDelay)
    {
        animationTick = 0;

        if (animationMode == ANIMATION_MODE_SCROLL_TEXT)
            this->updateScrollText();

        if (animationMode == ANIMATION_MODE_PRINT_TEXT)
            this->updatePrintText();

        if (animationMode == ANIMATION_MODE_SCROLL_IMAGE)
            this->updateScrollImage();

        if (animationMode == ANIMATION_MODE_ANIMATE_IMAGE)
            this->updateAnimateImage();

        if(animationMode == ANIMATION_MODE_PRINT_CHARACTER)
        {
            animationMode = ANIMATION_MODE_NONE;
            this->sendAnimationCompleteEvent();
        }
    }
}

/**
  * Broadcasts an event onto the shared MessageBus
  * @param eventCode The ID of the event that has occurred.
  */
void MicroBitDisplay::sendAnimationCompleteEvent()
{
    // Signal that we've completed an animation.
    MicroBitEvent(id,MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE);

    // Wake up a fiber that was blocked on the animation (if any).
    MicroBitEvent(MICROBIT_ID_NOTIFY_ONE, MICROBIT_DISPLAY_EVT_FREE);
}

/**
  * Internal scrollText update method.
  * Shift the screen image by one pixel to the left. If necessary, paste in the next char.
  */
void MicroBitDisplay::updateScrollText()
{
    image.shiftLeft(1);
    scrollingPosition++;

    if (scrollingPosition == width + MICROBIT_DISPLAY_SPACING)
    {
        scrollingPosition = 0;

        image.print(scrollingChar < scrollingText.length() ? scrollingText.charAt(scrollingChar) : ' ',width,0);

        if (scrollingChar > scrollingText.length())
        {
            animationMode = ANIMATION_MODE_NONE;
            this->sendAnimationCompleteEvent();
            return;
        }
        scrollingChar++;
   }
}

/**
  * Internal printText update method.
  * Paste in the next char in the string.
  */
void MicroBitDisplay::updatePrintText()
{
    image.print(printingChar < printingText.length() ? printingText.charAt(printingChar) : ' ',0,0);

    if (printingChar > printingText.length())
    {
        animationMode = ANIMATION_MODE_NONE;

        this->sendAnimationCompleteEvent();
        return;
    }

    printingChar++;
}

/**
  * Internal scrollImage update method.
  * Paste the stored bitmap at the appropriate point.
  */
void MicroBitDisplay::updateScrollImage()
{
    image.clear();

    if (((image.paste(scrollingImage, scrollingImagePosition, 0, 0) == 0) && scrollingImageRendered) || scrollingImageStride == 0)
    {
        animationMode = ANIMATION_MODE_NONE;
        this->sendAnimationCompleteEvent();

        return;
    }

    scrollingImagePosition += scrollingImageStride;
    scrollingImageRendered = true;
}

/**
  * Internal animateImage update method.
  * Paste the stored bitmap at the appropriate point and stop on the last frame.
  */
void MicroBitDisplay::updateAnimateImage()
{
    //wait until we have rendered the last position to give a continuous animation.
    if (scrollingImagePosition <= -scrollingImage.getWidth() + (MICROBIT_DISPLAY_WIDTH + scrollingImageStride) && scrollingImageRendered)
    {
        animationMode = ANIMATION_MODE_NONE;
        this->clear();
        this->sendAnimationCompleteEvent();
        return;
    }

    if(scrollingImagePosition > 0)
        image.shiftLeft(-scrollingImageStride);

    image.paste(scrollingImage, scrollingImagePosition, 0, 0);

    if(scrollingImageStride == 0)
    {
        animationMode = ANIMATION_MODE_NONE;
        this->sendAnimationCompleteEvent();
    }

    scrollingImageRendered = true;

    scrollingImagePosition += scrollingImageStride;
}

/**
  * Resets the current given animation.
  */
void MicroBitDisplay::stopAnimation()
{
    // Reset any ongoing animation.
    if (animationMode != ANIMATION_MODE_NONE)
    {
        animationMode = ANIMATION_MODE_NONE;

        // Indicate that we've completed an animation.
        MicroBitEvent(id,MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE);

        // Wake up aall fibers that may blocked on the animation (if any).
        MicroBitEvent(MICROBIT_ID_NOTIFY, MICROBIT_DISPLAY_EVT_FREE);
    }

    // Clear the display and setup the animation timers.
    this->image.clear();
}

/**
  * Blocks the current fiber until the display is available (i.e. not effect is being displayed).
  * Animations are queued until their time to display.
  *
  */
void MicroBitDisplay::waitForFreeDisplay()
{
    // If there's an ongoing animation, wait for our turn to display.
    if (animationMode != ANIMATION_MODE_NONE && animationMode != ANIMATION_MODE_STOPPED)
        fiber_wait_for_event(MICROBIT_ID_NOTIFY, MICROBIT_DISPLAY_EVT_FREE);
}


/**
  * Prints the given character to the display, if it is not in use.
  *
  * @param c The character to display.
  * @param delay Optional parameter - the time for which to show the character. Zero displays the character forever.
  * @return MICROBIT_OK, MICROBIT_BUSY is the screen is in use, or MICROBIT_INVALID_PARAMETER.
  *
  * Example:
  * @code
  * uBit.display.printAsync('p');
  * uBit.display.printAsync('p',100);
  * @endcode
  */
int MicroBitDisplay::printAsync(char c, int delay)
{
    //sanitise this value
    if(delay < 0)
        return MICROBIT_INVALID_PARAMETER;

    // If the display is free, it's our turn to display.
    if (animationMode == ANIMATION_MODE_NONE || animationMode == ANIMATION_MODE_STOPPED)
    {
        image.print(c, 0, 0);

        if (delay > 0)
        {
            animationDelay = delay;
            animationTick = 0;
            animationMode = ANIMATION_MODE_PRINT_CHARACTER;
        }
    }
    else
    {
        return MICROBIT_BUSY;
    }

    return MICROBIT_OK;
}

/**
  * Prints the given string to the display, one character at a time, if the display is not in use.
  * Returns immediately, and executes the animation asynchronously.
  *
  * @param s The string to display.
  * @param delay The time to delay between characters, in milliseconds. Must be > 0.
  * @return MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.
  *
  * Example:
  * @code
  * uBit.display.printAsync("abc123",400);
  * @endcode
  */
int MicroBitDisplay::printAsync(ManagedString s, int delay)
{
    //sanitise this value
    if(delay <= 0 )
        return MICROBIT_INVALID_PARAMETER;

    if (animationMode == ANIMATION_MODE_NONE || animationMode == ANIMATION_MODE_STOPPED)
    {
        printingChar = 0;
        printingText = s;
        animationDelay = delay;
        animationTick = 0;

        animationMode = ANIMATION_MODE_PRINT_TEXT;
    }
    else
    {
        return MICROBIT_BUSY;
    }

    return MICROBIT_OK;

}

/**
  * Prints the given image to the display, if the display is not in use.
  * Returns immediately, and executes the animation asynchronously.
  *
  * @param i The image to display.
  * @param x The horizontal position on the screen to display the image (default 0)
  * @param y The vertical position on the screen to display the image (default 0)
  * @param alpha Treats the brightness level '0' as transparent (default 0)
  * @param delay The time to delay between characters, in milliseconds. set to 0 to display forever. (default 0).
  *
  * Example:
  * @code
  * MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n");
  * uBit.display.print(i,400);
  * @endcode
  */
int MicroBitDisplay::printAsync(MicroBitImage i, int x, int y, int alpha, int delay)
{
    if(delay < 0)
        return MICROBIT_INVALID_PARAMETER;

    if (animationMode == ANIMATION_MODE_NONE || animationMode == ANIMATION_MODE_STOPPED)
    {
        image.paste(i, x, y, alpha);

        if(delay > 0)
        {
            animationDelay = delay;
            animationTick = 0;
            animationMode = ANIMATION_MODE_PRINT_CHARACTER;
        }
    }
    else
    {
        return MICROBIT_BUSY;
    }

    return MICROBIT_OK;
}

/**
  * Prints the given character to the display, and wait for it to complete.
  *
  * @param c The character to display.
  * @param delay The time to delay between characters, in milliseconds. Must be > 0.
  * @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
  *
  * Example:
  * @code
  * uBit.display.print('p');
  * uBit.display.print('p',100);
  * @endcode
  */
int MicroBitDisplay::print(char c, int delay)
{
    if (delay < 0)
        return MICROBIT_INVALID_PARAMETER;

    // If there's an ongoing animation, wait for our turn to display.
    this->waitForFreeDisplay();

    // If the display is free, it's our turn to display.
    // If someone called stopAnimation(), then we simply skip...
    if (animationMode == ANIMATION_MODE_NONE)
    {
        this->printAsync(c, delay);
        if (delay > 0)
            fiber_wait_for_event(MICROBIT_ID_DISPLAY, MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE);
    }
    else
    {
        return MICROBIT_CANCELLED;
    }

    return MICROBIT_OK;
}

/**
  * Prints the given string to the display, one character at a time.
  * Uses the given delay between characters.
  * Blocks the calling thread until all the text has been displayed.
  *
  * @param s The string to display.
  * @param delay The time to delay between characters, in milliseconds. Must be > 0.
  * @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
  *
  * Example:
  * @code
  * uBit.display.print("abc123",400);
  * @endcode
  */
int MicroBitDisplay::print(ManagedString s, int delay)
{
    //sanitise this value
    if(delay <= 0 )
        return MICROBIT_INVALID_PARAMETER;

    // If there's an ongoing animation, wait for our turn to display.
    this->waitForFreeDisplay();

    // If the display is free, it's our turn to display.
    // If someone called stopAnimation(), then we simply skip...
    if (animationMode == ANIMATION_MODE_NONE)
    {
        this->printAsync(s, delay);
        fiber_wait_for_event(MICROBIT_ID_DISPLAY, MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE);
    }
    else
    {
        return MICROBIT_CANCELLED;
    }

    return MICROBIT_OK;
}

/**
  * Prints the given image to the display.
  * Blocks the calling thread until all the text has been displayed.
  *
  * @param i The image to display.
  * @param delay The time to display the image for, or zero to show the image forever. Must be >= 0.
  * @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
  *
  * Example:
  * @code
  * MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n");
  * uBit.display.print(i,400);
  * @endcode
  */
int MicroBitDisplay::print(MicroBitImage i, int x, int y, int alpha, int delay)
{
    if(delay < 0)
        return MICROBIT_INVALID_PARAMETER;

    // If there's an ongoing animation, wait for our turn to display.
    this->waitForFreeDisplay();

    // If the display is free, it's our turn to display.
    // If someone called stopAnimation(), then we simply skip...
    if (animationMode == ANIMATION_MODE_NONE)
    {
        this->printAsync(i, x, y, alpha, delay);
        if (delay > 0)
            fiber_wait_for_event(MICROBIT_ID_DISPLAY, MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE);
    }
    else
    {
        return MICROBIT_CANCELLED;
    }

    return MICROBIT_OK;
}

/**
  * Scrolls the given string to the display, from right to left.
  * Uses the given delay between characters.
  * Returns immediately, and executes the animation asynchronously.
  *
  * @param s The string to display.
  * @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
  * @return MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.
  *
  * Example:
  * @code
  * uBit.display.scrollAsync("abc123",100);
  * @endcode
  */
int MicroBitDisplay::scrollAsync(ManagedString s, int delay)
{
    //sanitise this value
    if(delay <= 0)
        return MICROBIT_INVALID_PARAMETER;

    // If the display is free, it's our turn to display.
    if (animationMode == ANIMATION_MODE_NONE || animationMode == ANIMATION_MODE_STOPPED)
    {
        scrollingPosition = width-1;
        scrollingChar = 0;
        scrollingText = s;

        animationDelay = delay;
        animationTick = 0;