CFA-10052 Development Platform

2019-12-31 Update: This is now updated for the current hardware and on Github: https://github.com/crystalfontz/CFA10052-Custom-Firmware-Example

================================================================================================

CFA-10052 Module Introduction:
The Crystalfontz CFA-10052 is a versatile intelligent LCD module.
Both the Crystalfontz CFA735 and CFA835 products are based on the CFA-10052 hardware module.
The CFA-10052 (and so the CFA735 and CFA835) can be reprogrammed to run your own custom firmware.

Hardware features:

• ST Micro STM32F103RCT6 microcontroller
  ARM 32-bit Cortex™-M3 CPU @ 72 MHz
  256K x 8 Flash, 48K x 8 RAM
• A 244 x 68 pixel backlit LCD display
• Sitronix ST7529 32 grayscale graphic LCD controller
• Buck-boost switching supply allows wide (2.7v to 5.5v) supply voltage range
• Separate switching LED brightness controllers for keypad and LCD backlights
• 6 button backlit keypad
• 4x bi-color (red/green) LEDs
• USB2 interface
• microSD card slot
• Up to 20 general purpose IO pins (GPIO's)
• Multiple serial/SPI/I2C/CAN interfaces (depending on GPIO use).

The Development Platform:
The CFA-10052 Development Platform package is a quick-start to creating custom C/C++ firmware for the CFA-10052 module.
Package details:

• VirtualBox virtual machine image
• Linux Mint MATE desktop environment
• Eclipse programming environment (IDE)
• OpenOCD JTAG programming software
• Mentor Graphics CodeBench LE tools (GNU C compiler, linker, debugger, etc)
• Crystalfontz CFA-10052 firmware example source code

Software & Hardware Requirements:

• A Crystalfontz CFA10052 Module (or CFA735 / CFA835).
• A OpenOCD compatible JTAG interface.
• A decently powerful PC running Windows, Linux or OSX with Oracle VirtualBox installed (see below).
• The Development Package image files (see below).

Important Note:
The Crystalfontz CFA735 and CFA835 products are a CFA-10052 hardware module programmed with CFA735/CFA835 firmware.
The CFA735 and CFA835 firmware is not open-source, and cannot be copied off of the CFA-10052 by the user, nor can it be programmed on to the CFA-10052 by the user.
Once a CFA735 or CFA835 is programmed with custom firmware, the module will loose all CFA735/CFA835 functionality.
For a CFA-10052 module to be re-programmed with CFA735 or CFA835 firmware it will need to be physically returned to Crystalfontz.
Please email support@crystalfontz.com if you need more information on this topic.

Downloading the CFA-10052 Development Platform:
The Development Platform is approximately 2.2GBytes in size. To help with downloading, we have made it availiable in a few different formats.
The files are available for download from this website: http://images.crystalfontz.com/vm/cfa10052.
Option 1: Download the full-sized ZIP compressed archive file.
Option 2: Download the full-sized 7Zip compressed archive file (7Zip is required to extract this file).
Option 3: Download in 10 separate 7Zip archive file parts (7Zip is required to extract these files).
Once you have extracted the the Development Platform image file (named "CFA-10052 Development Platform.ova") from the 7Zip/ZIP file,
continue with the appropriate VirtualBox Installation step below.

Oracle VirtualBox Installation (Windows):

1. Download the latest Windows version of Oracle VirtualBox from this webpage.
2. Download the VirtualBox Extension Pack (found on the same webpage).
3. Install VirtualBox on your Windows PC by running the downloaded file in step 1.
4. Install the Extension Pack by double-clicking on the file downloaded in step 2 in Windows Explorer.
5. Open the VirtualBox Manager.
6. In the File menu, select "Import Appliance..."
7. In the import dialog, select the "CFA-10052 Development Platform.ova" file which was downloaded & extracted in the previous section.
8. Continue through the remaining import questions until the "CFA-10052 Development Platform" appears in the VirtualBox Manager VM list.
9. Start the VM by selecting "CFA-10052 Development Platform" and clicking the Start button in the toolbar.

Oracle VirtualBox Installation (Linux):

• Download and install Orcale VirtualBox (see the Oracle VirtualBox Linux Downloads website for installation options & guides).
• At a Linux console, use "sudo vboxmanage -import 'CFA-10052 Development Platform.ova'" to import the Development Platform VM.
• Start the VM using "vboxmanage -startvm ''CFA-10052 Development Platform'".

Oracle VirtualBox Installation (Apple OSX):

• Download & Install the latest version of Oracle VirtualBox for OSX from this webpage.
• Download & Install the VirtualBox Extension Pack (found on the same webpage).
• Open the VirtualBox Manager.
• In the File menu, select "Import Appliance..."
• In the import dialog, select the "CFA-10052 Development Platform.ova" file which was downloaded & extracted in the previous section.
• Continue through the remaining import questions until the "CFA-10052 Development Platform" appears in the VirtualBox Manager VM list.
• Start the VM by selecting "CFA-10052 Development Platform" and clicking the Start button in the toolbar.

Using The Development Environment:
Once the CFA-10052 Development Platform VM is running (see previous steps), you should see the the desktop displayed as in #1 screenshot below.

First, run the "Update Firmware Examples" script on the desktop.
This script will download any updates/additions to the example firmware source-code from GitHub.
You can view the GitHub repository here: https://github.com/crystalfontz/CFA-10052_Firmware_Examples

Secondly, see the "OpenOCD - JTAG Guide" document which is located on the desktop.
OpenOCD and a JTAG key will need to be connected to your CFA-10052 module before proceeding.

If you are re-programming a CFA735 or CFA835 module, see the "CFA735 and CFA835 Important Note" document on the desktop.
Also, as the CFA735 and CFA835 use the JTAG pins and use locked firmware, you will need to follow the steps under "Problems & Solutions"
in the "OpenOCD - JTAG Guide" document the first time you re-program the module.

Once OpenOCD is up and running in the background, run "Eclipse IDE" on the desktop.
When Eclipse starts, you'll see a list of of the firmware examples on the left.
"example_led-keypad" is the most simple firmware example, so it's a good starting point.
This example changes the state of the LED's and keypad backlight depending on which keypad buttons are pressed.

Below is a list of steps to open, view, compile and program one of the examples to your CFA-10052:

• Right click on "example_led-keypad" and choose "Open Project".
• Click on the little triangle to the left of the project to view its contents.
• Double-click on "main.c" to view the main firmware C source code file.
  The main() function is located at the end of the file. The main() function is where the
  main program loop is run that checks the keypad keys, and sets the LEDs / keypad brightness.
• At the top of the left pane in Eclipse, select the "Console" tab.
• Click on the "Project" menu, then click "Build Project".
• You should see compiling progress in the Console window.
  Any compiling errors will show up in here.
  When compiling is error-free and complete the last section (table) of text is the program size information. The ".text" line shows how much flash
  memory is used. In this example that is approx 19,000 bytes (about 5% of the total availiable 256kB of flash memory).
  This is quite a bit larger than usual due to this being a "debugging" build of the firmware.
• With the console view still selected, on the Eclipse Tool bar, click on the small down-arrow next to the green bug-like icon.
  Select "example_led-keypad Debug".
  This will cause Eclipse to connect to OpenOCD, erase the flash memory on the STM32F103, upload the example firmware into flash
  memory, then start running the firmware.
  You will also now be in Eclipse's "Debug" workspace, with debugging specific view options (to move back to the programming workspace,
  choose the "C/C++" tab in the top right of the Eclipse window).
  You should now see the 4th green LED on the CFA-10052 flashing, showing the firmware is running.
• To debug this firmware program, place a breakpoint somewhere in the main() functions main loop by select the source-code line, then
  choosing "Toogle Breakpoint" in the "Debug" menu (or use the Ctrl+Shift+B hotkey).
  Eclipse should now show the program paused at the location you selected (green led on the CFA-10052 will no longer be blinking).
  While the program is paused, you can use the Variables, Registers, Memory, etc views on the right side of the Eclipse window to
  inspect & debug the firmware.
• Press the green "play" icon in the Eclipse toolbar to have the firmware continue running.

Once you have tried the example firmware projects and are ready to create your own firmware, we suggest that you use one of the example
projects as a base which you then modify to your needs.

To keep the original example projects intact, you can duplicate a project by performing the following steps:

• Make sure the project you wish to duplicate is opened (Right click on the project name and choose "Open Project").
• Right click on the project name, and select "Copy"
• Right click in the project list (Project Explorer) and select "Paste"

Unfortunately Eclipse does not copy Debug Configurations to the new project. These will need to be copied manually by:

• Make sure both the newly created project, and the original project are open.
• On the Eclipse Tool bar, click on the small down-arrow next to the green bug-like icon, select "Debug Configurations..."
• Right-click on the original "xxxxx Debug" item under "GDB Hardware Debugging", select "Duplicate"
• Select the newly duplicated debug configuration
• Change the debugging configuration name at the top of the window (ie, "MyProject Debug").
• In the "Main" tab:
  - Change the filename under "C/C++ Application" using the new project name (ie "Debug/MyProject.elf").
  - Change the project using the "Browse..." button (ie "MyProject").
• In the "Startup" tab:
  - Under "initialization commands", scroll down the text window, and edit the bottom line to use the new output file location.
  Ie: monitor flash write_image ${workspace_loc}/MyProject/Debug/MyProject.bin 0x8000800
• Click on the "Debug" button to finish.

Support:
For any more information on the Development Environtment VM, firmware examples, or help with using them, see
the Crystalfontz CFA-10052 discussion forum.

Screenshots:
#1


#2