Pyes

Beginnings for a reuseable desktop interface for field-programming of Arduino devices.

Pyes

Pyes is a desktop application for programming embedded devices. It is currently in release 0.1.0.

Its source code can be found at https://github.com/simzes/pyes. Pyes is available with a BSD license; see the repository for more details.

Overview

Pyes is a desktop application that supports straightforward interaction with embedded devices. (Pyes stands for program-your-embedded-system.) It borrows from user interface concepts common in desktop computing, such as clicking on icons to open files, and makes these available for use with embedded devices; with pyes, clicks on icons upload applications to a tethered embedded device, in a sense “opening” the file on the device. This can make embedded devices approachable and usable.

Many embedded devices support configuration, but with interfaces that are complex or confusing for non-technical or untrained users. These sometimes involve button presses and holds, lights, and beeps that aid in navigating through a menu structure. Some devices might provide small screens, with limited visibility and navigation. These interfaces are limited because the devices are limited; the hardware and software to support these can take considerable time to develop, and take up significant resources on the device. With pyes, interactivity is implemented on the desktop-side, removing or reducing on-device resources.

Pyes is provided as an application template; it is filled in with a provider’s details and any customizations. Pyes supports uploading of a provided catalog onto any supported board; this catalog can be updated remotely. Facilities for customization are currently primitive, and brittle with any upstream changes to resource files; this will be addressed in the future.

Pyes is written in javascript, and is built on top of vue and node. Electron provides the desktop application framework; this packages the javascript code into a desktop application and installer that works on all platforms.

Pyes supports a number of boards in the Arduino environment. Internally, pyes relies on avrgirl-arduino for flashing arduino boards, and is limited to the boards supported by this package. See: https://github.com/noopkat/avrgirl-arduino#how-do-i-use-it.

Pyes is currently in release version 0.1.0; its development is just beginning. See the future features and release map below for information on future plans.

Demo landing page

Each program becomes a titled icon you can click and select.

demo landing catalog with some animals


Landing page after failed upload

When an icon is selected, its description fills in the sidebar. Above the description is feedback from a failed upload (no leonardo was plugged in).

demo landing catalog after failed upload


Main Components

Important Files

Main Process

The main process code is located in src/main/index.js. It is responsible for starting the renderer/interface process, loading the catalog, updating the remote catalog, and performing device uploads.

Interface Process

The interface process (renderer process, in electron terms) is located in src/renderer/App.vue, where a vue instance links with html and css to create the interface’s webpage. On start-up, it requests the catalog from the main process, and displays it. It responds to user navigation requests, and requests uploads of catalog.

Configuration

Pyes’s behavior can be modified by changing the configuration file in static/config.json. The config file example below has been annotated to explain behaviors:

{
  "window":  {              // config values for the application window's behavior
    "title": "your title here (from config)", // the window frame's title
    "width": 900,           // the initial width of the window
    "height": 600           // the initial height of the window
  },
  "remote_catalog": {       // config values for the remote catalog
                            // if stanza is completely absent, no remote updates are enabled
    "enable_updates": true, // default is true; if set to false, updates are disabled
    "username": "simzes",   // github username/repository/branch where the remote catalog is
    "repository": "test-bitty-catalog",
    "branch": "test-pyes"
  }
}

The default version of the pyes configuration is here: https://github.com/simzes/pyes/blob/master/static/config.json.

Catalog

A catalog defines a collection of programs presented to the user, what arduino board works with these programs, and other details about the author and source.

For each program, called an “entry”, several pieces of information tell the user about the program. These are an icon, its title, and an extended description. The icon is any image type that an html <img src="..."> element can use as its source. The description is a markdown file, shown in the selection sidebar when selected. A path to the binary file tells pyes which file to upload.

By convention, resources for each program are located in a unique folder, with the icon/description/binary files located relative to this. An example annotated program entry is below:

{
  "path": "donkey",               // path from catalog base to this entry
  "title": "Wish I was a donkey", // program title (displayed under icon)
  "icon": "donkey.jpg",           // relative path to the icon file
  "description": "donkey.md",     // path to the markdown file
  "binary": "donkey.hex"          // path to the binary
}

The "upload" stanza tells avrgirl which arduino board to use. The full list is here: https://github.com/noopkat/avrgirl-arduino#how-do-i-use-it

"upload": {
  "board": "leonardo"
}

Finally, several details are present in the "source" stanza; for remote updates to occur, the version field must change with catalog changes:

"source": {
  "name": "name of the catalog",
  "version": "0.1.0",
  "homepage": "wheretogo.com",
  "license": "type of license",
  "author": "simzes",
  "brief": "stuff that will display if there's no markdown",
  "description": "landing.md"
}

A complete example of a catalog index is here: https://github.com/simzes/pyes/blob/master/static/catalog/index.json.

Tasks and Workflows

Downloading and setting up pyes

Pyes should be downloaded as a git clone. To do this, create a new directory for your application, and inside it run: git clone https://github.com/simzes/pyes.git .

After this download, install the tools pyes needs to run and build; at a minimum, these are git, node and yarn. Windows and mac environments may need additional setup to enable developer modes. For mac, be sure to install xcode; there are some instructions here.

Once these have been installed, run yarn install to install all node and electron dependencies.

Finally, run yarn dev to run the developer application instance. If all is well, an application window with the default catalog will appear.

Building pyes

Once pyes has been downloaded, its dependencies installed, and yarn dev successfully runs the developer application, pyes can be built into a desktop installer. At this time, cross-platform builds are not supported, and each platform build must be carried out on that platform.

To build pyes into an installer, run: yarn build-<platform>

where <platform> is “mac”, “linux”, or “windows”. If all is well, this will produce an installer executable in build/.

Because of some library limitations, the command yarn run electron-rebuild may need to be run before yarn build.

Filling in details for an application

Several fields can be customized in package.json. These are the application name, author, homepage, and description, among others. The configuration file, in static/config.json specifies the app’s displayed window title in the window/title field.

Customizing System Icons

Pyes has a default icon of a smiling paperclip over a green background. This can be replaced.

In icons/, one icon each is present and named for mac, windows, and linux. These names are referenced in package.json; while these parameters may be renamed, it may be easier to rename or link the image into the currently named location.

Currently, only square icons are supported well; this can be changed in the css. (As is, rectangular icons are squished into a square, ignoring the aspect ratio.)

Because of icon ugliness across platforms, getting things right is tricky. This recipe works well to copy one icon into a file per platform:

Customizing CSS

Pyes’ CSS is specified at the bottom of App.vue (src/renderer/App.vue).

The application window is laid out with this scheme; here, css class names are followed by the element type, with a description of its contents:

Visually, this looks like this:

Line drawing of css layout with labels

Setting up a preinstalled catalog

The preinstalled catalog is sourced from the static/catalog directory; this is built into installed applications, and shown to users until a remote catalog is downloaded.

Catalog entries must be registered in the catalog’s index.json file, and placed in subdirectories of static/catalog.

Linking a remote catalog

A remote catalog can be linked into the application in the "remote_catalog" object, found in static/config.json; this specifies the github user, repository, and branch where the remote catalog is located. The index.json file must be in the base directory of this repository, and match the relative directory structure used in the preinstalled catalog.

Updating a remote catalog

Pyes checks for remote catalog updates when it starts up, and downloads it whenever the remote’s version differs from the catalog located on disk. If the catalog is valid, it is displayed to the user when the application starts up next.

To update a catalog, make any modifications to the catalog’s contents and index, and update the version listed in the index before pushing to github.

Testing a remote catalog update

It’s a good idea to test a remote catalog before pushing it out to user applications. This can be done in two ways; both are recommended. For both, any issues will show up in the application’s output. This can be viewed by running the application from the command line.

  1. Test the remote catalog update as a preinstalled catalog. To do this, copy the directory contents into the application’s static/catalog/ directory. Then, with the configuration parameter remote_catalog/enable_updates set to false, run the application in developer and installed modes. If the desired catalog appears, it is all set. (The modifications to the catalog can be undone by running git checkout static/catalog.)
  2. Test the remote catalog update in a test branch Pyes can use a different github branch as its remote catalog, allowing a test branch can be tested separately before all user applications. To do this, create a github branch containing the catalog updates; instead of pushing to the branch listed in the user application configs, push to a new remote branch. Then, with this branch listed in the config parameter remote_catalog/<branch> (and enable_updates set to true), run the development and installed application; on its second launch, the application should list the catalog.

Future Features and Release Roadmap

Past Releases and Key Features

0.1.0

Planned Future Releases and Features

0.2.0

Future Features