Moddable SDK – Getting Started

Copyright 2016-2017 Moddable Tech, Inc.

Revised: January 23, 2017

This document is a brief introduction to getting started with the Moddable SDK. It describes the organization of the source tree, how to build, and how to connect to the source level debugger.

Source tree

build

This build directory contains files to build the SDK.

• bin - binary output files generated by the build
• devices - files used for building for a specific platform, e.g. Synergy or ESP
• makefiles - make files that generate the build and compile the SDK for various targets. The make files for building on macOS are build/makefiles/mac and for Linux on build/makefiles/linux
• simulator - source code to the Moddable simulator
• tmp - object files generated by the build

customers/whirlpool

This directory contains applications developed specifically for Whirlpool.

documentation

The documentation directory contains the technical documentation for the Moddable SDK. All documentation files are in the Markdown format. The assets directory contains images referenced by the markdown.

• Commodetto.md - The Commodetto graphics framework
• die-cut.md - Getting started with the "die-cut" object in Piu, used to build efficient animations and transitions.
• handle.md - Using relocatable memory blocks in XS6.
• Manifest.md - The specification for the manifest JSON file used to build projects in the Moddable SDK
• piu.md - The Piu user interface framework, which implements a subset of the KinomaJS API.
• Poco.md - The Poco graphics rendering library, used by Commodetto and Piu.
• Tools.md - Reference documentation for the command line tools in the Moddable SDK, including mcconfig, mcrez, png2bmp, xsc6, xsl6, xsr6, and Screen Test, the desktop simulator.

examples

The examples directory contains small application projects that demonstrate how to use various features of the SDK.

• cryptdigest
• helloworld
• piu/balls
• piu/cards
• piu/countdown
• piu/drag
• piu/text
• piu/transitions
• timers
• uuid

libraries

The libraries directory contains third party SDK files to support specific device targets (e.g. Synergy, ESP).

modules

The modules directory contains the modules of the Moddable SDK. Each module is a JavaScript module, conforming to the ES6 module definition.

• base/debug - turn garbage collector on/off, get amount of free RAM
• base/timer - immediate, one shot, and repeating timers
• base/uuid - UUIT generator
• commodetto - graphics library
• crypt/digest - Digest and HMAC calculations using MD5, SHA1, SHA256, SHA224, SHA512, and SHA384
• data/base64 - Base64 encoding and decoding
• data/hex - BinHex encoding and decoding
• files/file - access to the host file system
• files/resource - access to named resources compiled into the binary
• piu - user interface framework

tools

The tools directory contains the source code for the tools used during development with the Moddable SDK.

• buildclut - converts Photoshop color table file (.act) to Commodetto color table file (.cct)
• mcconfig - make file generator that drives the build of applications
• mcrez - compiles files into a resource map for storage in the firmware
• png2bmp - converts PNG image files to BMP format, with pixel format conversion and 90 degree rotations
• xsc6 - XS6 compiler that converts JavaScript source code to XS6 byte code
• xsl6 - XS6 linker that combines multiple byte code files and generates declarations for C code.
• xsr6 - Runtime for XS6 tools.
• simulator - The desktop simulator, Screen-Test
• xsbug - The XS6 debugger

xs

The xs directory contains the source code to the XS6 JavaScript virtual machine.

Building

macOS

First, define the MODDABLE environment variable.

Next, add ${MODDABLE}/build/bin/mac/release to your PATH environment variable. (Edit the PATH variable in ~/.profile)

Then, build the tools. This includes xsc6, xsl6, xsr6, serial2xsbug, mcconfig, mcrez, png2bmp and the simulator

cd ${MODDABLE}/build/makefiles/mac
make

After building the tools, build an example by switching to the example's directory and invoking mcconfig:

cd ${MODDABLE}/examples/piu/balls
mcconfig -d -m -r 0 -f rgb565le -p mac

mcconfig builds the example, launches the simulator if it is not already running, and then opens the example.

Common mcconfig options include:

• -f - screen format (rgb565le, gray256, gray16, clut16)
• -r - screen rotation (0, 90, 180, 270)

Windows

First, define the MODDABLE environment variable

Next, run “Developer Command Prompt for VS2015" and enter:

cd %MODDABLE%\build\makefiles\win
build

Now add %MODDABLE%\build\bin\win\debug to the PATH environment variable.

To build an example, switch to the example's directory and invoke mcconfig by running "Developer Command Prompt for VS2015" and entering:

cd %MODDABLE%\examples\piu\balls
mcconfig -d -m

To use xsbug running on a remote machine (e.g. Mac), set the XSBUG_HOST environment variable on Windows to the IP address of the Mac running xsbug.

Synergy

Note: The following instructions assume the Moddable SDK is located at c:\moddable.

First, follow the instructions for building the tools on Windows. Then build the Whirlpool oven application from the "Developer Command Prompt for VS2015":

cd %MODDABLE%\customers\whirlpool\oven
mcconfig -d -m -p synergy -f CLUT16 -r 90

Next launch e2Studio and ensure the following settings:

• Cross ARM C Compiler
  • Includes
    • C:\moddable\xs\includes
    • C:\moddable\xs\sources\synergy
• Cross ARM C Linker
  • Miscellaneous
    • Other objects
      • C:\moddable\build\bin\synergy\clut16-90\debug\oven\xsr6.ar

Then do a Build Debug followed by Debug. When it breaks at ResetHandler() and main(), select continue.

Note: If you change the application, you will need to change the archive file location in Cross Arm C Linker -> Miscellaneous -> Other objects You will also need to remove the built files in the moddable tree to correctly build and archive the new files. ie. del /s /q %MODDABLE%\build\bin\synergy\clut16-90 %MODDABLE%\build\tmp\synergy\clut16-90 %MODDABLE%\build\tmp\synergy\debug

Debugging

The Simulator works with xsbug, the debugger for XS6. To use xsbug, launch xsbug prior to launching the simulator on the same computer. The simulator will automatically connect to xsbug. On macOS, xsbug is built as part of the tools build. On Windows, use xsbug as built by KinomaJS.

The simulator implementation is currently focused on graphics, consequently it is primarily for use with Piu and Commodetto. Of note, the Timer and File modules are unsupported.

Use of open source software

• KinomaJS - Apache
• Picojs, minigzip - public domain
• PCRE - PCRE library license
• Etc.

N.B. - license statements in source code are not always up-to-date. Do not rely on those as definitive.