GRiSP 2 Hardware Quickstart

🖥️ Software prerequisites: This guide assumes a Unix-like environment like Linux or macOS. WSL on Windows might work too if it has USB access. Prior setup of the development environment is required.

🛠️ Equipment prerequisites: This tutorial assumes that you have a GRISP 2 Board and a Micro-B USB cable, used for power and data transmission. An Ethernet cable may also be needed to connect to the board remotely.

Close-up of GRiSP 2 board

📖 Table of content

Boot Loader and Software
Guide
Navigation

Boot Loader and Software

GRiSP 2 ships with a boot loader (Barebox) and an Erlang demo application pre-installed on the built-in eMMC (Embedded MultiMediaCard) storage. If you connect an SD card, the default boot loader will try to boot from that instead (if there is anything bootable on it), otherwise it will boot from eMMC.

Guide

Power On

Make sure you don't have an SD card inserted to boot the pre-installed demo application from eMMC. Start by connecting your GRiSP 2 board via a Micro-B USB cable to your computer. The board should power on with the following LED sequence:

🔴 Red: this means the boot loader is running.
🟢 Green: Erlang VM has started and is loading.
🔵 Blue: The GRiSP demo application has started.
1. The second LED flashes red for 5 seconds
2. The second LED flashes random rainbow colors forever

GRISP2 Power On GIF

Connect over Serial

To connect to the Erlang node running on your board via the Micro-B USB serial interface, we recommend you use picocom. See this guide for how to install and find out which USB device to use.

In this guide we are using <</dev/example>> as a placeholder device. Keystrokes are represented in brackets (e.g. <enter>).

After connecting to the GRiSP board serial console, press the RESET button to view the full boot log.

GRISP2 RESET GIF

Initially, you'll observe the boot loader output until the Erlang VM starts, indicated by the first line beginning with [ERL] .... Once the boot process completes, you'll encounter an Erlang shell prompt with the node name shell@grispXXXXXX (where XXXXXX represents the serial number of your GRiSP board, padded with zeros if fewer than six digits).

$ picocom <</dev/example>> --baud 115200 --echo
<Press the RESET button on your GRiSP device>

barebox 2019.01.0-bsp-yocto-i.mx6ul-pd19.1.1 #10 Thu Dec 16 05:23:35 PST 2021


Board: PHYTEC phyCORE-i.MX6 Ultra Light SOM with eMMC
detected i.MX6 ULL revision 1.1
...
[ERL] Initializing
...
[ERL] Starting BEAM
uhub0: 1 port with 1 removable, self powered
uhub1: 1 port with 1 removable, self powered
warning: no interfaces have a carrier
ugen1.2: <Realtek 802.11n NIC> at usbus1
rtwn0: <Realtek 802.11n NIC, class 0/0, rev 2.00/0.00, addr 2> on usbus1
rtwn0: MAC/BB RTL8188EU, RF 6052 1T1R
Eshell V11.2.2.9  (abort with ^G)
(shell@grisp-XXXXXX)1>

Connecting Remotely via Ethernet

⚠️ Ethernet connection and cable required for this section

The best way to interact with an Erlang VM running on a GRiSP board is via an Erlang remote shell. Remote shells uses Erlang distribution to connect to another node over the network and present its shell as if it were a local shell.

graph LR;
   A[GRiSP Board Node] --- B[🛜 Internet] --- C[Computer Node]
   C -.-|Shell commands & responses| A

To explore distributed Erlang using the GRiSP demo image, you'll need to connect your GRiSP board to a network using an Ethernet cable. This connection allows your GRiSP board to communicate with other devices, like your computer, through the network.

It's important that the network you connect to has DHCP enabled, which is a system that automatically assigns IP addresses to devices on the network. This way, your GRiSP board can get its own unique address and join the network seamlessly.

Also, ensure that the computer you're using for this guide is connected to the same network. This ensures that your computer and GRiSP board can communicate with each other effectively.

Once you plug in the GRiSP board to Ethernet, you should observe the following messages printed, either when you plug the cable in or during boot if the cable is already connected:

...
info: ffec0: link state changed to UP
...
err: ffec0: ipv4_addroute: File exists
err: ffec0: ipv4_addroute: File exists
...

These messages may appear in a mixed order or interspersed with the regular Erlang output. The errors originate from the FreeBSD network stack and can generally be disregarded.

To verify that your GRiSP board has been assigned an IP address, use the inet module:

(shell@grisp-001001)4> inet:getifaddrs().
{ok,[{"ffec0",
      [{flags,[up,broadcast,running,multicast]},
       {addr,{65152,0,0,0,21037,62719,65059,41419}},
       {netmask,{65535,65535,65535,65535,0,0,0,0}},
       {addr,{192,168,X,Y}}, % This field should exist! It is the IP number of your board
       {netmask,{255,255,255,0}},
       {broadaddr,{192,168,X,255}},
       {hwaddr,"P-#"}]},
     ...
}

The IP address can be found in the addr field of the ffec0 network device. Once you have the IP address, you need to make your computer aware of it. You can do this by adding the following line to your /etc/hosts file:

192.168.X.Y grisp-XXXXXX

Replace 192.168.X.Y with the IP address assigned to your GRiSP board, and grisp-XXXXXX with the appropriate hostname obtained from the Erlang prompt displayed on your GRiSP board. The hostname format is typically shell@grisp-XXXXXX, where XXXXXX is the serial number of the board padded by zeros. Next, you can use Erlang to create a remote shell. The default Erlang cookie is grisp.

$ erl -sname my_remote_shell -remsh shell@grisp-XXXXXX -setcookie grisp
Erlang/OTP 23 [erts-11.2.2.8] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe]

Eshell V11.2.2.9  (abort with ^G)
(shell@grisp-001001)1>
(shell@grisp-001001)1> grisp_led:color(2, red).
ok

This shell provides a much more user-friendly experience than the serial connection. You have access to the full power of the regular Erlang shell, including features like tab completion and command history!

Things to Try

Hardware API

Once you have a working Erlang prompt, you can try some commands to interact with the GRiSP board hardware. Here are some examples:

Changing LED Color

(shell@grisp001001)1> grisp_led:color(1, yellow). % Set the first LED's color to yellow
ok

Reading jumper value. The jumpers are located in the Mode slot of the board.

GRISP2 JUMPERS GIF

(shell@grisp-001001)1> JMP1 = grisp_gpio:open(jumper_1, #{mode => input}). 
#Ref<0.1624234208.2812936193.181624>
(shell@grisp-001001)2> grisp_gpio:get(JMP1). 
0
% Then flip jumper 1 on the board
(shell@grisp-001001)3> grisp_gpio:get(JMP1). 
1

For more detailed information about functions of the GRiSP hardware platform, you can refer to the Erlang runtime library documentation.

Distributed Erlang

If you have completed the "Connecting remotely via Ethernet" stept, you can establish a distributed Erlang network:

Start Erlang shell with a specified node name and cookie. The cookie is a shared secret used for authentication in distributed Erlang systems.

$ erl -sname computer -setcookie grisp
Erlang/OTP 23 [erts-11.2.2.8] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe]

Eshell V11.2.2.8  (abort with ^G)
(computer@myhost)1>

Remote Board Interaction:

(computer@myhost)1> net_adm:ping('shell@grisp-001001'). %Send a ping to the board
pong
(computer@myhost)2> nodes().
['shell@grisp-001001']
(computer@myhost)5> rpc:call('shell@grisp-001001', io, format, [user, "foobar~n", []]).
ok % This should print the text "foobar" in the serial console of the GRiSP board

Navigation

You can find an index of all our tutorials, guides, and documentation on the front page of the wiki. We recommend starting with the tutorials available on the wiki.

🚀 If you have any questions or encounter issues, you can either open an issue here on GitHub, post on the GRISP forum,or join the Erlang Slack workspace and start a conversation in the GRISP channel. There, you'll find a community of users and developers ready to assist you with any queries or problems you may have.