jdbruijn/ledcube

Program to control an 8x8x8 RGB LED cube.

LedCube

LedCube is a project of making an 8x8x8 RGB LED cube. This repository contains the drawings, design, overview of the hardware and last but not least the code to control this 8x8x8 RGB LED cube.

LedCube is written in C and uses various peripherals like SPI, UART.

LedCube Visualisation

LedCube Visualisation is a Windows program that visualizes a 8x8x8 RGB LED cube and can be used to visualize a LED cube without risking of damaging the actual LED cube. In the future this program can possibly also be used to program the LedCube by visually programming sequences.

• Documentation can be found in the wiki, in the LedCube-Documentation project and on the LedCube Documentation site.
• Pull requests and bug reports are welcome!

Licensing

GNU General Public License version 3 or later, as published by the Free Software Foundation. Modification and redistribution are permitted according to the terms of the GPL. The license can be found in the LICENSE file.

ledcube's Issues

Debugging messages

Intro

It would be nice if there were files like debug.h and debug.c that contains functions or macros for debugging messages. This could be an global debug print function and a function that prints function calls. These functions should only be used when building the debug configuration, but the functions should still be available (but not doing anything) for compatibility when not building the debug configuration.

Steps

• Create debug.h and debug.c files with a simple debug_printf function;
• Add debugging messages to all initialize functions, for example LayerControl_init completed!;
• Create a debug_printfFunctionCall function for printing a function call, including the function's parameters. It would be great if such a function can keep track of the depth the debugging messages are printed. This way it should be possible to print debugging function call messages to a certain depth;
• Perform a small test for printing the function calls of several functions;
• Add the debug_printfFunctionCall to every function;
• Run the code and see if the debugging messages printed in a nice way.

Assertion messages keep printing infinitely

The assertion messages keeps printing. For example in Buzzer_set() there is an assertion for _time which, in case of a wrong time given as argument, keeps printing the error

source/LibraryFiles/src/Buzzer.c:86 _time >= BUZZER_MIN_TIME && _time <= BUZZER_MAX_TIME -- assertion failed>

This gets quite annoying if it's printed 1000 times..
Tried to alter the assert function to add an infinite loop, and making a custom assert define with an infinite loop. Both did not work.

Delay files

The delay functions are imported from libpic30.h which is a library from Microchip. This works fine, but the point is that FCY need to be defined before including the library, resulting in including System.h every time before including libpic30.h.
So it would be nice if there was a header file called Delay.h which does this and perhaps contains some more user friendly macros. The current macro for delay milliseconds for example is now __delay_ms() while it would be nicer to have a macro like Delay_ms() so Delay.h could contain such macros and wrap them to the Microchip library.

Standard printf with redirect instead of custom printf

Background info

Currently the custom Uart1_printf function is used which requires the following includes:

# include <stdio.h>           // For vsprintf() in Uartx_printf()
# include <stdarg.h>          // For Uartx_printf()
# include <string.h>          // For memset()

This results in a rather large increasement in the amount of bytes used in the program register (25% to 44% on 60663 bytes of programming memory). Using the standard printf function reduces this according to the functionality used. For example when only using printing a string without formatting, it goes from 25% to 26%, and when using formatting it goes to about 30%. So this is quite a difference that is very welcome.

Steps

• Find out usages of stderr and alike streams;
• Put the current Uart1_NNN functions inside a #if 0 equally block;
• Replace all the calls to Uart1_printf with calls to printf idem for putc and puts;
• For assert and debug see if it should use the same stream as the standard output or whether a different stream could be used and implement those features accordingly;
• Check whether it is possible to use one of the printf, puts or putc for the functions Uart1_putNum and Uart1_putBits and implement those features. Otherwise rewrite the putNum and putBits functions to drop the Uart1_ prefixes and use putc for printing inside those functions;
• Check whether tghe gets-family functions could be used instead of Uar1_gets and change those features accordingly.

Controlling a single layer

Milestone when a single layer can be controlled

Steps

• Write a function that uses a loop or loops to set certain 'pixels' in a layer, using the LedCube_setPixel function. To begin with a pattern could be red, green, blue, red, green, blue, red, green for row one, and so on.
• Test if the data is correctly set in the CubeData by printing in to a terminal and checking the pattern.
• Install the boot loader on the MCU and make sure the MCU is programmable using the the boot loader program and a custom linker script.
• Check whether the configuration bits are right because the configuration bits can only be set at the time of writing the boot loader to the MCU. This check could be performed by checking reading the bits from the registers (if possible) or by pulsing an output pin and checking the frequency on a scope.
• Write a function that outputs a colour on a single led of every row one at a time in a loop with a delay.
• Connect all the wires to the PanelControl PCBs and check with the previously written function whether the wires are correctly connected. And close the LedCube box.
• Use the function written in step one to check if all LEDs could be written with the right colour.
• Write functions to make all the LEDs of one row a certain colour and check whether this function works correctly by enabling the LEDs one after another, going from coordinate (0, 0, z) to (7, 7, z).

Convert code to the C99 standard

Background info

Currently the XC16 compiler in MPLAB X standard uses the C89 standard. However it is possible with the -std=c99 option to use the C99 standard. Although this is still quite an old standard is has some 'new' features that could come in handy.

Step 1

Make/find a list of the new features. This will result in a list of features that should be changed in the code.

• for (int i = 0; i < 99; ++i) { ... } instead of having the declaration of i outside the for loop;
• ???

Step 2

Update the code in the files below to the 'new' standard.

• Animations/Fill.h
• Animations/src/Fill.c
• CubeControl/Colours.h
• CubeControl/CubeControlData.h
• CubeControl/LayerControl.h
• CubeControl/LedCube.h
• CubeControl/LedDriver.h
• CubeControl/PanelControl.h
• CubeControl/src/CubeControlData.c
• CubeControl/src/LayerControl.c
• CubeControl/src/LedCube.c
• CubeControl/src/LedDriver.c
• CubeControl/src/PanelControl.c
• LibraryFiles/BitOperations.h
• LibraryFiles/Buzzer.h
• LibraryFiles/Debug.h
• LibraryFiles/Delay.h
• getPICConfigurationBits.h
• LibraryFiles/Interrupts.h
• LibraryFiles/IOPorts.h
• LibraryFiles/Macro.h
• LibraryFiles/MyAssert.h
• LibraryFiles/PeripheralPinSelect.h
• LibraryFiles/Ports.h
• LibraryFiles/SwFifoBuffer.h
• LibraryFiles/System.h
• LibraryFiles/Uart.h
• LibraryFiles/src/BitOperations.c
• LibraryFiles/src/Buzzer.c
• LibraryFiles/src/getPICConfigurationBits.c
• LibraryFiles/src/IOPorts.c
• LibraryFiles/src/SwFifoBuffer.c
• LibraryFiles/src/System.c
• LibraryFiles/src/Uart.c
• src/main.c
• Visualisation/LedCubeVisualisation.h
• Visualisation/src/LedCubeVisualisation.c
• version.h

Step 3

Informative announcement:
Make clear, in the wiki or somewhere else, that the C99 standard is used for programming.

Remove self tests and use unit tests

In a few files there is currently a define like PC_ENABLE_SELF_TEST_NO which enables or disables the 'self test' or as it should be called unit test. It would be better to have that in the code but have an external file for the unit test. A unit test framework that could be used is greatest.

Switching CubeData buffer

The data structure for the LedCube is below. This contains two CubeDataNN structure arrays.

typedef struct {
    uint32_t red;
    uint32_t green;
    uint32_t blue;
}RowControlData_t, *pRowControlData_t, *pCubeData_t;

typedef struct {
    RowControlData_t CubeData0[8][8];
    RowControlData_t CubeData1[8][8];
    pCubeData_t pCubeDataBase;
    const BamRoundMasks_t BamRoundMask[4];
    const uint8_t BamRoundShift[4];
}CubeControlData_t, *pCubeControlData_t;

Currently there is the function below to initialize the CubeData pointer to the first CubeData buffer. It would be nice if there was a function like this to switch between the two buffers.

CubeData_init( const pCubeControlData_t _pCubeControlData )

Debugging function call messages with indent

Intro

See #3 for motivation.

It would be nice if the function call debug messages have indent so it is easier to keep track of the function calls.
So the debugging messages now look like this:

 DEBUG: LayerControl_update(806, b06, 0, 0)
 DEBUG: PanelControl_update(806, b06, 0, 6, 0)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: PanelControl_update(806, b06, 0, 4, 0)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: PanelControl_update(806, b06, 0, 2, 0)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: PanelControl_update(806, b06, 0, 0, 0)
 DEBUG: LedDriver_update(0x0001)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedDriver_update(0x0000)
 DEBUG: LedCube_setPixel(b06, 0, 0, 0, 0, 0, 2)

But it would look nicer if they looked like this:

 DEBUG: LayerControl_update(806, b06, 0, 0)
  DEBUG: PanelControl_update(806, b06, 0, 6, 0)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
  DEBUG: PanelControl_update(806, b06, 0, 4, 0)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
  DEBUG: PanelControl_update(806, b06, 0, 2, 0)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
  DEBUG: PanelControl_update(806, b06, 0, 0, 0)
   DEBUG: LedDriver_update(0x0001)
   DEBUG: LedDriver_update(0x0000)
   DEBUG: LedDriver_update(0x0000)
 DEBUG: LedCube_setPixel(b06, 0, 0, 0, 0, 0, 2)

Initialize ports

All ports that are not set in the IOPorts_init() need to be set as digital outputs (see PIC24FJ64GA004 reference manual paragraph 2.8 for more info) and driven to a default state of '0' or '1'.
This needs to be done in the IOPorts_init function. Maybe even using a macro with a mask to set all unset ports as digital outputs.

License change (MIT to GPLv3)

I want to use the GPLv3 instead of the MIT license. I've never made a release so I can still change the license. The reason for this change is that this program works together with the LedCube Visualisation program, which is written in C++ using Qt. As far as I know Qt demands the usage of the GPL, so I want to be consistent in the LedCube related projects and have it all under the same license.

Files

• Animations/Fill.h
• Animations/src/Fill.c
• CubeControl/Colours.h
• CubeControl/CubeControlData.h
• CubeControl/LayerControl.h
• CubeControl/LedCube.h
• CubeControl/LedDriver.h
• CubeControl/PanelControl.h
• CubeControl/src/CubeControlData.c
• CubeControl/src/LayerControl.c
• CubeControl/src/LedCube.c
• CubeControl/src/LedDriver.c
• CubeControl/src/PanelControl.c
• LibraryFiles/BitOperations.h
• LibraryFiles/Buzzer.h
• LibraryFiles/Debug.h
• LibraryFiles/Delay.h
• getPICConfigurationBits.h
• LibraryFiles/Interrupts.h
• LibraryFiles/IOPorts.h
• LibraryFiles/Macro.h
• LibraryFiles/MyAssert.h
• LibraryFiles/PeripheralPinSelect.h
• LibraryFiles/Ports.h
• LibraryFiles/SwFifoBuffer.h
• LibraryFiles/System.h
• LibraryFiles/Uart.h
• LibraryFiles/src/BitOperations.c
• LibraryFiles/src/Buzzer.c
• LibraryFiles/src/getPICConfigurationBits.c
• LibraryFiles/src/IOPorts.c
• LibraryFiles/src/SwFifoBuffer.c
• LibraryFiles/src/System.c
• LibraryFiles/src/Uart.c
• src/main.c
• Visualisation/LedCubeVisualisation.h
• Visualisation/src/LedCubeVisualisation.c
• version.h

The license

The license in the files should look like:

 * 
 * This file is part of LedCube.
 * 
 * Copyright (c) 2015  Jeroen de Bruijn  <[email protected]>
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *

The license in the LICENSE file should look like this.

LedCube Visualisation

Intro

I have another project for visualizing this LED cube called LedCube-Visualisation. This project consists of a Windows program written in C# that currently visualizes a single layer of the LED cube.
The link between this program is currently made using UART and could in the future be made using a Bluetooth connection.

Connection

The connection between the LedCube Visualisation program and the LedCube code should be done using a defined and efficient data protocol and using several functions to output the data.

Steps

• Define a data protocol that includes layer, row, column, colours (rgb) and brightness (0-15).
• Create LedCubeVisualisation header and source files.
• Create a function that outputs the data of a single row.
• Test this function by viewing the output on a terminal and checking if the column, colour and brightness are printed correctly.
• Create a function that takes a data buffer as argument and outputs the data of a single layer using the function to output the data of a single row.
• Update the LedCube Visualisation program to be compatible with the newly defined data protocol.
• Test the code of outputting a single layer in combination with the LedCube Visualisation program.

Doxygen code documentation

It would be nice if the code documentation was compatible with the Doxygen code documentation guidelines. For more info, see http://www.stack.nl/~dimitri/doxygen/manual/index.html
This should contain these three steps.

Step 1

Document all files, including the functions.

• Animations/Fill.h
• Animations/src/Fill.c
• CubeControl/Colours.h
• CubeControl/CubeControlData.h
• CubeControl/LayerControl.h
• CubeControl/LedCube.h
• CubeControl/LedDriver.h
• CubeControl/PanelControl.h
• CubeControl/src/CubeControlData.c
• CubeControl/src/LayerControl.c
• CubeControl/src/LedCube.c
• CubeControl/src/LedDriver.c
• CubeControl/src/PanelControl.c
• LibraryFiles/BitOperations.h
• LibraryFiles/Buzzer.h
• LibraryFiles/Debug.h
• LibraryFiles/Delay.h
• getPICConfigurationBits.h
• LibraryFiles/Interrupts.h
• LibraryFiles/IOPorts.h
• LibraryFiles/Macro.h
• LibraryFiles/MyAssert.h
• LibraryFiles/PeripheralPinSelect.h
• LibraryFiles/Ports.h
• LibraryFiles/SwFifoBuffer.h
• LibraryFiles/System.h
• LibraryFiles/Uart.h
• LibraryFiles/src/BitOperations.c
• LibraryFiles/src/Buzzer.c
• LibraryFiles/src/getPICConfigurationBits.c
• LibraryFiles/src/IOPorts.c
• LibraryFiles/src/SwFifoBuffer.c
• LibraryFiles/src/System.c
• LibraryFiles/src/Uart.c
• src/main.c
• Visualisation/LedCubeVisualisation.h
• Visualisation/src/LedCubeVisualisation.c
• version.h

Step 2

Change the templates to be compatible with the Doxygen code documentation guidelines as well.

• C Source File
• C Main File
• C Header File
• C++ Source File
• C++ Main File
• C++ Header File
• C++ Class
• class.h

Step 3

Use consistent layout in all files for functions, declarations, everything. See some coding guidelines on the internet to determine which coding guideline to use.

• Animations/Fill.h
• Animations/src/Fill.c
• CubeControl/Colours.h
• CubeControl/CubeControlData.h
• CubeControl/LayerControl.h
• CubeControl/LedCube.h
• CubeControl/LedDriver.h
• CubeControl/PanelControl.h
• CubeControl/src/CubeControlData.c
• CubeControl/src/LayerControl.c
• CubeControl/src/LedCube.c
• CubeControl/src/LedDriver.c
• CubeControl/src/PanelControl.c
• LibraryFiles/BitOperations.h
• LibraryFiles/Buzzer.h
• LibraryFiles/Debug.h
• LibraryFiles/Delay.h
• getPICConfigurationBits.h
• LibraryFiles/Interrupts.h
• LibraryFiles/IOPorts.h
• LibraryFiles/Macro.h
• LibraryFiles/MyAssert.h
• LibraryFiles/PeripheralPinSelect.h
• LibraryFiles/Ports.h
• LibraryFiles/SwFifoBuffer.h
• LibraryFiles/System.h
• LibraryFiles/Uart.h
• LibraryFiles/src/BitOperations.c
• LibraryFiles/src/Buzzer.c
• LibraryFiles/src/getPICConfigurationBits.c
• LibraryFiles/src/IOPorts.c
• LibraryFiles/src/SwFifoBuffer.c
• LibraryFiles/src/System.c
• LibraryFiles/src/Uart.c
• src/main.c
• Visualisation/LedCubeVisualisation.h
• Visualisation/src/LedCubeVisualisation.c
• version.h

Software FIFO buffer, overflow error

The <bufferOverflowFlag> is currently not handled at all. This flag is automatically set by the sw fifo buffer but never cleared, where it should be cleared by the user (after handling the overflow).

For now the receiving program stops functioning because the overflow flag is never handled or cleared.