README.md
Blockware

A collection of programs meant to run on the blocks.

Table of contents


Getting Started
PlatformIO CLI
Protips
Demos


Getting Started

All of these blockwares are configured to be compiled and uploaded using <![CDATA[]]>PlatformIO<![CDATA[]]>. You can probably also use the Arduino IDE or any other tool that works to compile and upload Arduino-compatible code with ESP8266 processors.

The easiest way to get started is using <![CDATA[]]>Visual Studio Code (VSCode)<![CDATA[]]> with the <![CDATA[]]>PlatformIO extension<![CDATA[]]>.


Install VSCode either from the <![CDATA[]]>website<![CDATA[]]> or (on macOS) using Homebrew brew cask install visual-studio-code.
With VSCode open select View -> Extensions and search for PlatformIO IDE.
Click the extension and click Install.


File -> Open Workspace... and select the workspace.code-workspace file in one of the blockware folders (e.g. blockware/curvy-snake)

NOTE: In the workspace, you should have the PlatformIO actions available at the bottom of your VSCode




Connect your block to the computer using a Micro USB cable
Turn it on using the switch in the back
Press the Upload button (looks like a right arrow) in the Platform IO actions (bottom of your VSCode)

NOTE: The program should compile and then upload to your block. It can also be handy to use the Serial Monitor to view any logs from the program that are output over the USB serial port.

If the upload fails with an error message like Error: Please specify upload_port for environment or Timed out waiting for packet header, then you may need to edit the <![CDATA[]]>platformio.ini<![CDATA[]]> in the blockware's directory to set a specific upload_port. Look in /dev/ for a tty device named something like usbserial or ttyUSB or wchusbserial and change upload_port to match the path to that device exactly.
That's it, you should see the demo running on your block!

For more info on using the PlatformIO VSCode extension check out the <![CDATA[]]>PlatformIO Quick Start guide<![CDATA[]]>.



Using the PlatformIO CLI

You can alternately use the PlatformIO CLI if that's more your style. Follow one of the <![CDATA[]]>installation methods on the PlatformIO site<![CDATA[]]>. As of this writing, they recommend using their installer script:

python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)"


The script will probably instruct you to add something to your PATH in order to use the pio binary. Something like the following (which you could add to your .bashrc / .zshrc)

export PATH=$HOME/.platformio/penv/bin:$PATH


You can now build and upload blockware from the command line like this:

cd blockware/curvy-snake
pio run --target upload


Or if you want to override the upload_port (e.g. for blockwares that support WiFi OTA programming)

cd blockware/gif-download
pio run --target upload --upload-port gif-example.local


Protips

Serial Monitor Reset

In the VSCode PlatformIO Serial Monitor, you can quickly restart the block by pressing Ctrl-T Ctrl-D twice. This toggles the DTR pin on the USB-serial chip and that pin is connected to the RST pin on the microcontroller.

Logging using Dlog.h

If using the DLog library for logging over the serial monitor or telnet you need to add #define SERIALLOG 1 or #define TELNETLOG 1 respectively before including DLog.h to enable serial logging. For example, for logging to the serial port:

#define SERIALLOG 1


include <DLog.h>



If using TELNETLOG then from your computer you can do something like the following to get the logs to your terminal over the network.

telnet homeassistant-display.local


Demo Blockwares

This repo contains a handful of example blockwares you could run directly or use as a starting point to make your own blockware! Please share back any neat things you make so that others can benefit from it!

90fps



A demo of how to squeeze every last bit of graphics performance out of your block by making better use of the hardware SPI APIs in the microcontroller. The interesting bits are in the <![CDATA[]]>README.md<![CDATA[]]>.

Adafruit Example



A fork of Adafruit's <![CDATA[]]>SSD1351 OLED example code<![CDATA[]]> with the delays removed. Useful as an overview of the available graphics APIs in the Adafruit GFX library or as a graphics benchmark when tweaking the Adafruit GFX Library code (as detailed in the <![CDATA[]]>90fps README.md<![CDATA[]]>).

Bouncing Logo



The most 90s-est demo we've got. Bounce the Twitter logo around your screen just like your DVD player did to prevent burn-in on your CRT TV in 1999.

Curvy Snake



It's kinda like those old pipes screensavers, or snake with curves. Watch randomly generated curves snake around your block's screen.

Gif Download



This demo shows a QR code that takes you to a web page where you can upload a gif, have it translated to a block-friendly format, then the block can download it and begin to display it.

Requires a Node.js-based server component which you can find in in the gif-download/server directory.

Homeassistant Display



An example of a program that can connect to a <![CDATA[]]>Home Assistant<![CDATA[]]> home automation interface and display sensor values on the screen.

JPEG Download Example



An example that downloads a JPEG and displays it on the block.

Pixel Dust



An example that uses the <![CDATA[]]>Adafruit Pixel Dust<![CDATA[]]> to create animated dust that interacts with the accelerometer and a static Twitter Logo.

RGB LED



An example that uses the (normally not-included) internal RGB LED. This requires modification of the PCB by soldering on an RGB LED. This is probably not the blockware you're looking for.

Snake



The game of snake! This demo creates a WiFi access point that you can connect to on your phone to control the snake.

Stocks and Weather



An example that downloads stocks and weather.

Video Display

An example of real-time video streaming from your computer to your block.

<![CDATA[]]><![CDATA[]]>