Unofficial Guide To Expanding Your Numworks/Getting your development environment set up

The Numworks SDK

Numworks has gone and done a wonderful thing - they've published the entire source code and SDK for the calculator on GitHub and are actively maintain it with the latest releases and bug fixes. Anyone who has played around with the idea of writing their own code for a graphing calculator know that this is an amazing 180° about face from the typical calculator manufacturer. An overview and the GitHub link are available on the Numworks SDK page, but the documentation is understandably sparse, so let's get you up and running with a functioning development environment.

Windows 10 using Msys2

Windows may not be the ideal open source embedded development platform, but it sure is prolific and is an easy starting point. Thanks to the Msys2 project, it's fairly easy to get a Linux-style development environment up and running for Epsilon (the Numworks operating system).

Installing and configuring Msys2

Download and run the Msys2 installer by following all the instructions at http://www.msys2.org/. This section will assume you installed the 64-bit Msys2 environment at c:/msys64, and you'll need to adjust the listed paths if you installed somewhere else. This will get you a functioning command line, but without any development tools (not even, gasp, vi). So next up is to get the development tool chain installed by entering this command:

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-freetype mingw-w64-x86_64-fltk git make bison python vim

Next, you'll need to add the mingw64 tools to your path as well as the ARM complier for the ARM M4 processor used by the calculator. You'll install the compiler in a few steps, but we'll add the path while we are here.

Step by step:

• Go to 'c:\msys64\etc\skel'.
• Open '.bash_profile' document.
• Add the following command export PATH=/mingw64/bin:/c/arm/bin:$PATH at the end of the document.
• Save the document.
• Go to 'c:\msys64\home\[YOUR USERNAME]'.
• Open '.bash_profile' document.
• Add the following command export PATH=/mingw64/bin:/c/arm/bin:$PATH at the end of the document.
• Save the document.

Reopen the Msys2 terminal and type echo $PATH. If all worked, you should see the /mingw64/bin and /c/arm/bin paths listed among several others.

Installing the ARM compiler

The ARM compiler is not part of Msys2, but it is freely available from the ARM download page.

1. Go to the ARM download page and download the .ZIP file for Windows 32 (there is no 64 bit version.)
2. Open up the .ZIP file and extract all the contents to a new folder C:/arm/.
3. You should now have several folders one of which is C:/arm/bin. Since we already added this directory to your PATH earlier, it's all ready to go.

Setting up Git and cloning the source

You'll need git to download the SDK from GitHub as well as to manage your revisions as you develop new code.

1. Install the SSL certificates needed for using git with HTTPS. pacman -S mingw-w64-x86_64-ca-certificates ca-certificates
2. Tell git to use these certificates. git config --system http.sslcainfo /mingw64/ssl/certs/ca-bundle.crt
3. If you need to use a proxy then do export http_proxy=<insert http proxy address:port here> and export https_proxy=<insert https proxy address:port here>. If you are not sure, then try it first without. If that fails, then talk to whoever runs your network to get the correct proxy information.
4. When you clone the SDK repository, it will get created in a folder called epsilon in the current directory, so create and move to the directory you want to work from. For example: mkdir numworks then cd numworks.
5. Now you can clone the SDK repository with git clone https://github.com/numworks/epsilon.git

Your first build

At long last it's time to build the firmware!

1. Change to the epsilon directory cd epsilon
2. make MODEL=n01x0 clean
3. make MODEL=n01x0 where x is either 0 or 1. You can find your model # on the back of your calculator.

Your computer will churn for awhile compiling all the code. It's possible you'll see some warnings during the compile, but you can likely ignore them. If you get errors, you'll have to read the messages and see if you can figure out the problem. If all else fails, try going back to the last tagged release in the repository.

NOTE: if you have an issue with a file called "ft2build.h" or any error including "pkg-config" you should consider doing pacman -S mingw-w64-x86_64-pkg-config

Setting up the USB Drivers

In just a moment you'll download your newly compiled firmware to your calculator using a program called dfu-util. However, the default drivers USB drivers that get installed and tied to your calculator the first time you plug it in will not work for development, so we are going to use a program called Zadig to tell Windows to point your calculator to the standard Windows USB drivers instead.

1. Before we start let's get the easiest step out of the way, press on the reset button behind of your calculator using a paper clip or a pencil. Don't forget that this will delete all your custom scripts!
2. Installing drivers.
   1. Search for 'Numworks Workshop' on Google.
   2. The official website will ask you to login. Create an account if needed and login.
   3. You will see a button called 'Update my device', click on it.
   4. Click on the following page, the 'Download the driver' button and install the drivers.
3. Download the latest version of Zadig and run it.
4. Plug the calculator back into USB and press the RESET button. (Yep, again. You'll be doing this alot as you test code.)
5. In Zadig's Options menu, be sure "List All Devices" is checked.
6. In the drop down list of devices, select 'NumWorks Calculator' (might also occur as 'STM32 BOOTLOADER').
7. The USB ID should be 0483 DF11 or A291, and the driver will likely say STTub30.
8. You need to replace STTub30 with WinUSB, so select that to the right of the green arrow.
9. Click "Replace Driver" and Zadig will install the new driver.
10. Once the success message is displayed you can close Zadig.
11. Unplug the calculator from USB and press the RESET button.

Uploading your firmware

At long last you get to download your newly built firmware to the calculator... after we install one more piece: dfu-util.

1. Download the latest Windows release .ZIP from http://dfu-util.sourceforge.net/releases/
2. Open up the .ZIP and copy dfu-util-static.exe into your Msys2 /usr/local/bin directory. Create the bin directory if needed.
3. Rename the copy to dfu-util.exe
4. Plug the calculator into USB and press the RESET button. (Yes, again. Told you this will happen often.)
5. Now you can finally, from the epsilon directory, run make MODEL=n01x0 epsilon_flash where x is either 0 or 1. You can find your model number printed on the back of the calculator.

At the command line, you should see a short message that your device is about to be flashed and giving instructions to RESET the device. Then several messages about opening and claiming the DFU device followed by a progress bar of the download. When it finishes the calculator will reset on it's own and boot your newly downloaded firmware! You likely won't see any differences, because you we're likely already running the latest firmware, but the firmware running on your calculator was built right on your computer from source code that you can now modify.

Congratulations! You are now an Epsilon developer. Take a few minutes to go visit http://numworks.com and https://www.reddit.com/r/numworks and say a big thank you to Numworks for making this great device truly Open Source!

Linux

Installing the ARM compiler

The ARM compiler is freely available from the ARM download page.

1. Go to the ARM download page and download the .tar.bz2 file for Linux 64 bit (there is no 32 bit version.)
2. Extract all the contents to /opt : sudo tar xvjpf /path/to/downloaded/gcc-arm-none-eabi-6-2017-q2-update-linux.tar.bz2 -C /opt. If you do not have sudo privileges, you can extract to ~.
3. You should now have several folders one of which is /opt/gcc-arm-none-eabi-6-2017-q2-update/bin. Add this folder to your PATH: export PATH=$PATH:/opt/gcc-arm-none-eabi-6-2017-q2-update/bin

Installing other needed software and cloning the source

You'll need git to download the SDK from GitHub as well as to manage your revisions as you develop new code.

1. Install git and dfu-util
   1. On Gentoo and Gentoo based (funtoo, calculate, ...): emerge -v git dfu-util freetype bison flex fltk
   2. On Debian and Debian based (Ubuntu, ...) apt-get install git dfu-util build-essential libfreetype6-dev bison flex libfltk1.3-dev May be you have to install other dependencies.
   3. On Arch Linux sudo pacman -S git dfu-util freetype2 base-devel fltk libpng
   4. Others ...
2. When you clone the SDK repository, it will get created in a folder called epsilon in the current directory, so create and move to the directory you want to work from. For example: mkdir numworks then cd numworks.
3. Now you can clone the SDK repository with git clone https://github.com/numworks/epsilon.git

Your first build

At long last it's time to build the firmware!

1. Change to the epsilon directory cd epsilon where x is either 0 or 1 depending on your model. The model can be found on the back of the calculator.
2. make MODEL=n01x0 clean
3. make MODEL=n01x0 USERNAME="yourusername" Replace username with the name you want to appear on the About screen. The quotes are necessary.

Your computer will churn for awhile compiling all the code. It's possible you'll see some warnings during the compile, but you can likely ignore them. If you get errors, you'll have to read the messages and see if you can figure out the problem. If all else fails, try going back to the last tagged release in the repository.

Uploading the firmware to your calculator

At long last you get to upload your newly built firmware to the calculator.

1. Plug the calculator into USB and press the RESET button.
2. Run make app_flash from the epsilon directory.
3. Run make epsilon_flash from the epsilon directory to upload the new SDK to the calculator (ERASE ALL PROGRAMS AND DATA : save your work first on Numworks site).

At the command line, you should see a short message that your device is about to be flashed and giving instructions to RESET the device. Then several messages about opening and claiming the DFU device followed by a progress bar of the download. When it finishes the calculator will reset on it's own and boot your newly downloaded firmware! You likely won't see any differences, because you we're likely already running the latest firmware, but the firmware running on your calculator was built right on your computer from source code that you can now modify.

Congratulations! You are now an Epsilon developer. Take a few minutes to go visit http://numworks.com and https://www.reddit.com/r/numworks and say a big thank you to Numworks for making this great device truly Open Source!