Difference between revisions of "BeagleBoard/BeagleWire"

From eLinux.org
Jump to: navigation, search
(Quick Start Guide)
 
(10 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
<big>'''BeagleWire - FPGA development cape for the BeagleBone'''</big>
 
<big>'''BeagleWire - FPGA development cape for the BeagleBone'''</big>
  
The BeagleWire is an FPGA development platform that has been designed for use with BeagleBone boards. BeagleWire is a cape on which there is FPGA device - Lattice iCE40HX. The Lattice iCE40 is a family of FPGAs with a minimalistic architecture and very regular structure, designed for low-cost, high-volume consumer and system applications. The significance of FPGAs is continuously increasing, as they are more and more often used for supporting work of ARM processors. BeagleWire does not require external tools (JTAG) and the whole software is Open Source. iCE40 is an energy saving device, allowing to work with small batteries. FPGA cape allows easy and low cost start for beginners who would like to take their first steps in working with FPGAs. The developed software will be an easy and, at the same time, efficient tool for communication with FPGA. At this point FPGA will be able to meet the requirements of even more advanced applications. The BeagleWire creates a powerful and versatile digital cape for users to create their imaginative digital designs.  
+
The BeagleWire is an FPGA development platform that has been designed for use with BeagleBone boards. BeagleWire is a cape on which there is an FPGA device - Lattice iCE40HX. The Lattice iCE40 is a family of FPGAs with a minimalistic architecture and very regular structure, designed for low-cost, high-volume consumer and system applications. The significance of FPGAs is continuously increasing, as they are more and more often used to support ARM processors. BeagleWire does not require external tools (JTAG) and the whole software is Open Source. iCE40 is an energy saving device, allowing to work with small batteries. FPGA cape allows easy and low cost start for beginners who would like to take their first steps in working with FPGAs. The developed software will be an easy and, at the same time, efficient tool for communication with FPGA. At this point FPGA will be able to meet the requirements of even more advanced applications. The BeagleWire creates a powerful and versatile digital cape for users to create their imaginative digital designs.
  
 
__TOC__
 
__TOC__
Line 21: Line 21:
 
* lower application costs
 
* lower application costs
 
* fully open-source toolchain
 
* fully open-source toolchain
 +
  
 
====BeagleWire Peripherals:====
 
====BeagleWire Peripherals:====
Line 32: Line 33:
  
 
====Software\Driver support====
 
====Software\Driver support====
BeagleWire software support is still developing. You can find there a lot of useful examples and ready to use solutions. For communication between FPGA and ARM, We can use the GPMC. This is an easy and efficient solution. BeagleWire software repostitory has special components for it. You can just mapping your logic in BeagleBone memory. A lot of examples has kernel driver e.g. SPI, GPIO. After preparing the FPGA device you can use it as typical GPIO/SPI from user space. A part of examples which don't belong to kernel subsystems e.g. rotary excoder, ultrasonic ranger sensor or blink leds. In this examples You can connect which FPGA using write/read operation for /dev/mem file.
+
BeagleWire software support is still developing. A lot of useful examples and ready to use solutions can be found there. For communication between FPGA and ARM, GPMC can be used. This is an easy and efficient solution. BeagleWire software repository has special components for it. You can just map your logic in BeagleBone memory. A lot of examples have kernel driver e.g. SPI, GPIO. After preparing the FPGA device you can use it as a typical GPIO/SPI from user space. A part of examples do not belong to kernel subsystems e.g. rotary excoder, ultrasonic ranger sensor or blink leds. In these examples, you can connect to FPGA using write/read operation for /dev/mem file.
  
 
====Authors====
 
====Authors====
The project is the result of the community work and it is still developing. If you can support this project or do you have any questions, feel free to ask as.<br>
+
The project is the result of the community work and it is still under development. If you can support this project or if you have any questions, feel free to contact us.<br>
 
Michael Welling mwelling@ieee.org <br>
 
Michael Welling mwelling@ieee.org <br>
 
Patryk Mezydlo mezydlo.p@gmail.com <br>
 
Patryk Mezydlo mezydlo.p@gmail.com <br>
Line 53: Line 54:
  
 
======GPMC Communications interface======
 
======GPMC Communications interface======
The general-purpose memory controller (GPMC) is a unified memory controller dedicated to interfacing external memory devices: SRAM-like memories and application-specific integrated circuit (ASIC) devices, asynchronous, synchronous, and page mode (only available in non-multiplexed mode) burst NOR flash devices, NAND Flash, Pseudo-SRAM devices. The GPMC bus allow for a high bandwidth interface between the FPGA and the ARM processor. GPMC controller is configured from the DTS file. GPMC pins are brought out to BeagleBone P8/P9 headers. BeagleWire software repository contains a component writing in Verilog which support communications between FPGA and ARM.
+
The general-purpose memory controller (GPMC) is a unified memory controller dedicated to interfacing external memory devices: SRAM-like memories and application-specific integrated circuit (ASIC) devices, asynchronous, synchronous, and page mode (only available in non-multiplexed mode) burst NOR flash devices, NAND Flash, Pseudo-SRAM devices. The GPMC bus enables a high bandwidth interface between the FPGA and the ARM processor. GPMC controller is configured from the DTS file. GPMC pins are brought out to BeagleBone P8/P9 headers. BeagleWire software repository contains a component written in Verilog which supports communication between FPGA and ARM.
  
 
======SPI Programming interface======
 
======SPI Programming interface======
Programming is done by SPI interface. BeagleWire uses second BeagleBone SPI port. SPI frequency should be between 1Mhz and 25Mhz.  
+
Programming is done by SPI interface. BeagleWire uses second BeagleBone SPI port. SPI frequency should be between 1Mhz and 25Mhz.
  
 
======PMOD Expansion Ports======
 
======PMOD Expansion Ports======
BeagleWire contains four Digilent Inc. Pmod ports. The Pmod standard has a lot of ready modules. Thanks to four Pmod ports We can use as many as 24 additional pins.
+
BeagleWire contains four Digilent Inc. Pmod ports. The Pmod standard has a lot of ready modules. Thanks to four Pmod ports we can use as many as 24 additional pins.
  
 
======LEDs======
 
======LEDs======
There are four blue LEDs.  
+
There are four blue LEDs.
  
 
======DIP Switch======
 
======DIP Switch======
BeagleWire has two DIP switch. "ON" position is treated as logical zero.  
+
BeagleWire has two DIP switch. "ON" position is treated as logical zero.
  
 
======Push Button======
 
======Push Button======
There are two user buttons. We used schmitt trigger, this is simple structure which protect us from buttons bouncing. You can use buttons without worries.
+
There are two user buttons. We used schmitt trigger, a simple structure which prevents buttons bouncing.  
  
 
======Additional common IRQ lines======
 
======Additional common IRQ lines======
Two lines are connected directly between BBB and BW. These lines don't have destiny. In many application there are using as interrupt lines.
+
Two lines are directly connecting BBB and BW. These lines do not have intended use. In many applications they are used as interrupt lines.
  
 
======SDRAM Memory======
 
======SDRAM Memory======
BealgeWire has 32 MB  SDRAM memory. BeagleWire software repository contains a simple SDRAM controller writing in Verilog which support communications between SDRAM and ICE40 without.  
+
BealgeWire has 32 MB  SDRAM memory. BeagleWire software repository contains a simple SDRAM controller written in Verilog which supports communication between SDRAM and iCE40.  
 
+
 
======Grove Expansion Ports======
 
======Grove Expansion Ports======
BeagleWire contains four Grove connectors. First and second connectors used to I2C. Other connectors don't have destinations.
+
BeagleWire contains four Grove connectors. First and second connectors are used as I2C. Other connectors have no destinations.
  
 
======External clock source======
 
======External clock source======
BeagleWire has external clock generator. There is 100Mhz You can change clock speed using internal PLL.  
+
BeagleWire has an external 100 Mhz clock generator. Clock speed can be changed using internal PLL.  
  
 
======Pinout======
 
======Pinout======
More information about I/O connections you can find in:[https://github.com/pmezydlo/BeagleWire/blob/master/beaglewire_pinmap.pcf BeagleWire pcf file] or [https://github.com/mwelling/beagle-wire/blob/master/plots/beagle-wire.pdf BeagleWire Schematic]
+
More information about I/O connections can be found at:[https://github.com/pmezydlo/BeagleWire/blob/master/beaglewire_pinmap.pcf BeagleWire pcf file] or [https://github.com/mwelling/beagle-wire/blob/master/plots/beagle-wire.pdf BeagleWire Schematic]
 +
 
 +
======Connecting BeagleWire with BeagleBone (P8/P9 Connector Pin Usage)======
 +
 
  
 
==Quick Start Guide==
 
==Quick Start Guide==
 +
====<big>Use pre-prepared BBB image</big>====
 +
Pre-prepared sd-card BBB image can be found here: [https://rcn-ee.net/rootfs/bb.org/testing/BeagleWire/ BBB image]  The image contains all required  drivers and scripts to start BeagleWire development.
 +
 +
Download image:
 +
<pre>$ wget https://rcn-ee.net/rootfs/bb.org/testing/BeagleWire/BeagleWire-image.tar.xz</pre>
 +
 +
Verify image:
 +
<pre>
 +
$ sha256sum BeagleWire-image.tar.xz
 +
eb862b8898b821627909952854688b46b93778fff4164c7c096453025ec7caeb
 +
</pre>
 +
 +
Unpack image and write the image to the memory card (please check if you have the correct SD card device — in my case it is /dev/sdd):
 +
<pre>
 +
$ tar xf BeagleWire-image.tar.xz
 +
$ sudo dd if=image.img of=/dev/sdX
 +
</pre>
 +
 +
It should be noted that the Beaglewire image requires a newer version of U-Boot on the eMMC to properly load the devicetree overlay for the FPGA manager.
 +
The easiest way update the bootloader on the eMMC is loading the latest image from Beagleboard.org.
 +
 +
Reference the following pages to create a MicroSD card for updating the eMMC with the latest image:<br>
 +
[https://beagleboard.org/latest-images Beagleboard.org latest images]<br>
 +
[https://beagleboard.org/getting-started#update MicroSD card creation instructions]<br>
 +
[https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Flashing_eMMC Instructions of updating the MicroSD for automatic eMMC programming]<br>
 +
 +
Once the BBB is loaded with the latest image, insert the MicroSD, power cycle and it should boot into the quick start image.
 +
The default login is as follows:
 +
<pre>
 +
username: debian
 +
password: temppwd
 +
</pre>
 +
 +
====<big>Programming the FPGA from the BeagleBone</big>====
 +
Pre-prepared BBB image contains directory (/home/debian/load-fw) with required scripts, drivers and a simple blink example.
 +
Load bitstream to FPGA:
 +
<pre>
 +
$ cd /home/debian/load-fw/
 +
$ ./bw-prog.sh blink.bin
 +
</pre>
 +
 +
To check how programming is proceeding, use:
 +
<pre>$ dmesg</pre>
 +
Results should look like this:
 +
<pre>
 +
[ 2427.827170] Starting FPGA loader
 +
[ 2427.830561] fpga_manager fpga0: writing blink.bin to Lattice iCE40 FPGA Manager
 +
[ 2428.012162] Stopping FPGA loader
 +
</pre>
 +
 +
====<big>Synthesizing Verilog code using IceStorm toolchain</big>====
 +
Prepare Verilog module for first FPGA programming<br>
 +
top.v:<br>
 +
<pre>
 +
module top(input clk, output [3:0] led);
 +
 +
reg [27:0] counter = 0;
 +
always @(posedge clk) counter <= counter + 1;
 +
 +
assign led[0:3] = counter[24:27];
 +
endmodule
 +
</pre>
 +
 +
PCF file is used for connecting input/output module signals with physical pins in FPGA device.<br>
 +
pinmap.pcf:<br>
 +
<pre>
 +
# USER CLOCK
 +
set_io clk 61
 +
 +
# LED
 +
set_io led[0] 28
 +
set_io led[1] 29
 +
set_io led[2] 31
 +
set_io led[3] 32
 +
</pre>
 +
 +
Makefile:<br>
 +
<pre>
 +
PROJ = blink
 +
BUILD = ./out
 +
DEVICE = 8k
 +
FOOTPRNT = tq144:4k
 +
 +
SRC = top.v
 +
SRC +=
 +
PIN_SRC = pinmap.pcf
 +
 +
.PHONY: all load clean
 +
 +
all:
 +
        mkdir -p $(BUILD)
 +
        yosys -q -p "synth_ice40 -top top -blif $(BUILD)/$(PROJ).blif" $(SRC)
 +
        arachne-pnr -d $(DEVICE) -P $(FOOTPRNT) -p $(PIN_SRC) -o $(BUILD)/$(PROJ).asc $(BUILD)/$(PROJ).blif
 +
        icepack $(BUILD)/$(PROJ).asc $(BUILD)/$(PROJ).bin
 +
        echo -e "\x0\x0\x0\x0\x0\x0\x0" >> $(BUILD)/$(PROJ).bin
 +
 +
load:
 +
        sh /home/debian/load-fw/bw-prog.sh $(BUILD)/$(PROJ).bin
 +
 +
clean:
 +
        rm -rf ./$(BUILD)/
 +
</pre>
 +
 +
To build the above example:
 +
<pre>make</pre>
 +
To load bitstream to FPGA:
 +
<pre>make load</pre>
 +
 +
==Other Guides==
  
 
====<big>Prepare BBB Image</big>====
 
====<big>Prepare BBB Image</big>====
You have to prepare custom kernel image, is easy instruction how to do it here: ''[https://eewiki.net/display/linuxonarm/BeagleBone+Black BBB prepare image instruction].'' You have to attach(<M>) FPGA-mgr and iCE40-spi driver. Version of Your linux kernel should be 4.12 or newest.  
+
Prepare a custom kernel image, an easy instruction on how to do it can be found here: ''[https://eewiki.net/display/linuxonarm/BeagleBone+Black BBB prepare image instruction].'' Attach(<M>) FPGA-mgr and iCE40-spi driver. Linux kernel should be version 4.12 or newer.
 +
<pre>
 +
Device Drivers ---> FPGA Configuration Support --->  <M> FPGA Configuration Framework
 +
                                                      <M>      Lattice iCE40 SPI 
 +
</pre>
 +
 
 +
====<big>Writing EEPROM configuration contents</big>====
 +
BeagleWire cape has a EEPROM memory, so that the BBB device overlay is automatically loaded up on each boot up. EEPROM contents and loading script are located in BeagleWire software repository. <br>
 +
Check BW_EEPROM.bin content:
 +
<pre>$ xxd  BW_EEPROM.bin</pre>
 +
It should look like this:<br>
 +
<pre>
 +
00000000: aa55 33ee 4131 4265 6167 6c65 426f 6e65  .U3.A1BeagleBone
 +
00000010: 2042 6561 676c 6557 6972 6543 6170 6500  BeagleWireCape.
 +
00000020: 0000 0000 0000 3030 4130 6265 6167 6c65  ......00A0beagle
 +
00000030: 626f 6172 642e 6f72 6700 4257 2d49 4345  board.org.BW-ICE
 +
00000040: 3430 4361 7065 0000 0000 3030 4257 5245  40Cape....00BWRE
 +
00000050: 5630 3230 3137 0000 0000 0000 0000 0000  V02017..........
 +
</pre>
 +
Load EEPROM using script:
 +
<pre>$ sudo ./load_eeprom.sh</pre>
  
====<big>Writeing EEPROM configuration contents</big>====
+
====<big>Device Tree Overlay</big>====
BeagleWire cape has a EEPROM memory, so that the BBB device overlay is automatically loaded up on each boot up. EEPROM contents and loading script are located in BeagleWire software repository.  
+
Device Tree is required for enabling SPI and GPMC.<br>
<div style="font-size: 13.3333339691162px; line-height: 20.7999992370605px; border: 1px solid rgb(204, 204, 204); padding: 5px 10px; background: rgb(238, 238, 238);">sudo ./load_eeprom.sh</div>
+
Install the DTS compiler:<br>
 +
<pre>
 +
$ wget -c https://raw.githubusercontent.com/RobertCNelson/tools/master/pkgs/dtc.sh
 +
$ chmod +x dtc.sh
 +
$ ./dtc.sh
 +
</pre>
 +
Compile the dts file:
 +
<pre>
 +
$ dtc -O dtb -o DTS/BW-ICE40Cape-00A0.dtbo -b 0 -@ DTS/BW-ICE40Cape-00A0.dts
 +
</pre>
 +
Copy dtbo file to /lib/firmware on the BBB:
 +
<pre>
 +
$ cp BW-ICE40Cape-00A0.dtbo /lib/firmware
 +
</pre>
  
 
====<big>Installing the IceStorm toolchain</big>====
 
====<big>Installing the IceStorm toolchain</big>====
You can install toolchain on PC or BBB.<br>
+
Install toolchain on PC or BBB.<br>
 
On PC:
 
On PC:
<div style="font-size: 13.3333339691162px; line-height: 20.7999992370605px; border: 1px solid rgb(204, 204, 204); padding: 5px 10px; background: rgb(238, 238, 238);">sudo ./install_IceStorm.sh</div>
+
<pre>$ sudo ./install_IceStorm.sh</pre>
  
 
On BBB:
 
On BBB:
<div style="font-size: 13.3333339691162px; line-height: 20.7999992370605px; border: 1px solid rgb(204, 204, 204); padding: 5px 10px; background: rgb(238, 238, 238);">sudo ./install_IceStorm.sh BBB</div>
+
<pre>$ sudo ./install_IceStorm.sh BBB</pre>
 
 
====<big>Synthesizing Verilog code using IceStorm toolchain</big>====
 
 
 
 
 
====<big>Programming the FPGA from the BeagleBone</big>====
 
You have to prepare custom kernel image, is easy instruction how to do it here: ''[https://eewiki.net/display/linuxonarm/BeagleBone+Black BBB prepare image instruction]
 
For programming We use SPI. You have to install overlay for enabling SPI and GPMC.
 
  
 
====<big>Examples</big>====
 
====<big>Examples</big>====
BeagleWire software repository has a lot of different source. Here I'm showing you how to use it. We can divided examples for two parts. The first part is the simplest examples which don't have own subsystem in Linux kernel e.g. rotary excoder, ultrasonic ranger sensor or blink leds. In this examples We can connect which FPGA using write/read operation for /dev/mem file.
+
BeagleWire software repository has a lot of different sources. The following description shows how to use it. Examples can be divided into two parts. The first part is the simplest examples which do not have their own subsystem in Linux kernel e.g. rotary excoder, ultrasonic ranger sensor or blink leds. In these examples we can connect with FPGA using write/read operations for /dev/mem file. The second part consists of examples with kernel driver e.g. SPI, GPIO.

Latest revision as of 12:09, 22 August 2018


BeagleWire

Bw title.jpg

BeagleWire - FPGA development cape for the BeagleBone

The BeagleWire is an FPGA development platform that has been designed for use with BeagleBone boards. BeagleWire is a cape on which there is an FPGA device - Lattice iCE40HX. The Lattice iCE40 is a family of FPGAs with a minimalistic architecture and very regular structure, designed for low-cost, high-volume consumer and system applications. The significance of FPGAs is continuously increasing, as they are more and more often used to support ARM processors. BeagleWire does not require external tools (JTAG) and the whole software is Open Source. iCE40 is an energy saving device, allowing to work with small batteries. FPGA cape allows easy and low cost start for beginners who would like to take their first steps in working with FPGAs. The developed software will be an easy and, at the same time, efficient tool for communication with FPGA. At this point FPGA will be able to meet the requirements of even more advanced applications. The BeagleWire creates a powerful and versatile digital cape for users to create their imaginative digital designs.

BeagleWire features:

  • FPGA: Lattice iCE40HX4K - TQFP 144 Package
  • GPMC port access from the BeagleBone
  • SPI programming port from the BeagleBone
  • 4 layer PCB optimized design to support maximum performance for high bandwidth applications
  • BeagleBoard optimized - compatible with BeagleBone Black, BeagleBone Black Wireless, element14 BeagleBone Black Industrial
  • does not require external tools (JTAG)
  • minimalistic architecture and very regular structure
  • energy saving device allows to work with small batteries
  • lower application costs
  • fully open-source toolchain


BeagleWire Peripherals:

  • 32 MB SDRAM
  • 100Mhz external clock
  • 4 LEDs
  • 4 PMOD connectors
  • 4 Grove connectors
  • 2 user push buttons
  • 2 input DIP switch

Software\Driver support

BeagleWire software support is still developing. A lot of useful examples and ready to use solutions can be found there. For communication between FPGA and ARM, GPMC can be used. This is an easy and efficient solution. BeagleWire software repository has special components for it. You can just map your logic in BeagleBone memory. A lot of examples have kernel driver e.g. SPI, GPIO. After preparing the FPGA device you can use it as a typical GPIO/SPI from user space. A part of examples do not belong to kernel subsystems e.g. rotary excoder, ultrasonic ranger sensor or blink leds. In these examples, you can connect to FPGA using write/read operation for /dev/mem file.

Authors

The project is the result of the community work and it is still under development. If you can support this project or if you have any questions, feel free to contact us.
Michael Welling mwelling@ieee.org
Patryk Mezydlo mezydlo.p@gmail.com

Resources

BeagleWire KiCAD Repository
BeagleWire Software Repository
BeagleWire Hackaday.io project page
BeagleWire Hackster.io project page
BeagleWire Schematic

User Manual

Board Diagram

Bw diagram.png

Expansion Ports, Interfaces and Peripherals

GPMC Communications interface

The general-purpose memory controller (GPMC) is a unified memory controller dedicated to interfacing external memory devices: SRAM-like memories and application-specific integrated circuit (ASIC) devices, asynchronous, synchronous, and page mode (only available in non-multiplexed mode) burst NOR flash devices, NAND Flash, Pseudo-SRAM devices. The GPMC bus enables a high bandwidth interface between the FPGA and the ARM processor. GPMC controller is configured from the DTS file. GPMC pins are brought out to BeagleBone P8/P9 headers. BeagleWire software repository contains a component written in Verilog which supports communication between FPGA and ARM.

SPI Programming interface

Programming is done by SPI interface. BeagleWire uses second BeagleBone SPI port. SPI frequency should be between 1Mhz and 25Mhz.

PMOD Expansion Ports

BeagleWire contains four Digilent Inc. Pmod ports. The Pmod standard has a lot of ready modules. Thanks to four Pmod ports we can use as many as 24 additional pins.

LEDs

There are four blue LEDs.

DIP Switch

BeagleWire has two DIP switch. "ON" position is treated as logical zero.

Push Button

There are two user buttons. We used schmitt trigger, a simple structure which prevents buttons bouncing.

Additional common IRQ lines

Two lines are directly connecting BBB and BW. These lines do not have intended use. In many applications they are used as interrupt lines.

SDRAM Memory

BealgeWire has 32 MB SDRAM memory. BeagleWire software repository contains a simple SDRAM controller written in Verilog which supports communication between SDRAM and iCE40.

Grove Expansion Ports

BeagleWire contains four Grove connectors. First and second connectors are used as I2C. Other connectors have no destinations.

External clock source

BeagleWire has an external 100 Mhz clock generator. Clock speed can be changed using internal PLL.

Pinout

More information about I/O connections can be found at:BeagleWire pcf file or BeagleWire Schematic

Connecting BeagleWire with BeagleBone (P8/P9 Connector Pin Usage)

Quick Start Guide

Use pre-prepared BBB image

Pre-prepared sd-card BBB image can be found here: BBB image The image contains all required drivers and scripts to start BeagleWire development.

Download image:

$ wget https://rcn-ee.net/rootfs/bb.org/testing/BeagleWire/BeagleWire-image.tar.xz

Verify image:

$ sha256sum BeagleWire-image.tar.xz
eb862b8898b821627909952854688b46b93778fff4164c7c096453025ec7caeb

Unpack image and write the image to the memory card (please check if you have the correct SD card device — in my case it is /dev/sdd):

$ tar xf BeagleWire-image.tar.xz
$ sudo dd if=image.img of=/dev/sdX

It should be noted that the Beaglewire image requires a newer version of U-Boot on the eMMC to properly load the devicetree overlay for the FPGA manager. The easiest way update the bootloader on the eMMC is loading the latest image from Beagleboard.org.

Reference the following pages to create a MicroSD card for updating the eMMC with the latest image:
Beagleboard.org latest images
MicroSD card creation instructions
Instructions of updating the MicroSD for automatic eMMC programming

Once the BBB is loaded with the latest image, insert the MicroSD, power cycle and it should boot into the quick start image. The default login is as follows:

username: debian
password: temppwd

Programming the FPGA from the BeagleBone

Pre-prepared BBB image contains directory (/home/debian/load-fw) with required scripts, drivers and a simple blink example. Load bitstream to FPGA:

$ cd /home/debian/load-fw/
$ ./bw-prog.sh blink.bin

To check how programming is proceeding, use:

$ dmesg

Results should look like this:

[ 2427.827170] Starting FPGA loader
[ 2427.830561] fpga_manager fpga0: writing blink.bin to Lattice iCE40 FPGA Manager
[ 2428.012162] Stopping FPGA loader

Synthesizing Verilog code using IceStorm toolchain

Prepare Verilog module for first FPGA programming
top.v:

module top(input clk, output [3:0] led);

	reg [27:0] counter = 0;
	always @(posedge clk) counter <= counter + 1;

	assign led[0:3] = counter[24:27];
endmodule

PCF file is used for connecting input/output module signals with physical pins in FPGA device.
pinmap.pcf:

# USER CLOCK
set_io clk 61

# LED
set_io led[0] 28
set_io led[1] 29
set_io led[2] 31
set_io led[3] 32 

Makefile:

PROJ = blink
BUILD = ./out
DEVICE = 8k
FOOTPRNT = tq144:4k

SRC = top.v
SRC +=
PIN_SRC = pinmap.pcf

.PHONY: all load clean

all:
        mkdir -p $(BUILD)
        yosys -q -p "synth_ice40 -top top -blif $(BUILD)/$(PROJ).blif" $(SRC)
        arachne-pnr -d $(DEVICE) -P $(FOOTPRNT) -p $(PIN_SRC) -o $(BUILD)/$(PROJ).asc $(BUILD)/$(PROJ).blif
        icepack $(BUILD)/$(PROJ).asc $(BUILD)/$(PROJ).bin
        echo -e "\x0\x0\x0\x0\x0\x0\x0" >> $(BUILD)/$(PROJ).bin

load:
        sh /home/debian/load-fw/bw-prog.sh $(BUILD)/$(PROJ).bin

clean:
        rm -rf ./$(BUILD)/

To build the above example:

make

To load bitstream to FPGA:

make load

Other Guides

Prepare BBB Image

Prepare a custom kernel image, an easy instruction on how to do it can be found here: BBB prepare image instruction. Attach(<M>) FPGA-mgr and iCE40-spi driver. Linux kernel should be version 4.12 or newer.

 Device Drivers ---> FPGA Configuration Support --->  <M> FPGA Configuration Framework 
                                                      <M>      Lattice iCE40 SPI   

Writing EEPROM configuration contents

BeagleWire cape has a EEPROM memory, so that the BBB device overlay is automatically loaded up on each boot up. EEPROM contents and loading script are located in BeagleWire software repository.
Check BW_EEPROM.bin content:

$ xxd  BW_EEPROM.bin

It should look like this:

00000000: aa55 33ee 4131 4265 6167 6c65 426f 6e65  .U3.A1BeagleBone
00000010: 2042 6561 676c 6557 6972 6543 6170 6500   BeagleWireCape.
00000020: 0000 0000 0000 3030 4130 6265 6167 6c65  ......00A0beagle
00000030: 626f 6172 642e 6f72 6700 4257 2d49 4345  board.org.BW-ICE
00000040: 3430 4361 7065 0000 0000 3030 4257 5245  40Cape....00BWRE
00000050: 5630 3230 3137 0000 0000 0000 0000 0000  V02017..........

Load EEPROM using script:

$ sudo ./load_eeprom.sh

Device Tree Overlay

Device Tree is required for enabling SPI and GPMC.
Install the DTS compiler:

$ wget -c https://raw.githubusercontent.com/RobertCNelson/tools/master/pkgs/dtc.sh
$ chmod +x dtc.sh
$ ./dtc.sh

Compile the dts file:

$ dtc -O dtb -o DTS/BW-ICE40Cape-00A0.dtbo -b 0 -@ DTS/BW-ICE40Cape-00A0.dts

Copy dtbo file to /lib/firmware on the BBB:

$ cp BW-ICE40Cape-00A0.dtbo /lib/firmware

Installing the IceStorm toolchain

Install toolchain on PC or BBB.
On PC:

$ sudo ./install_IceStorm.sh

On BBB:

$ sudo ./install_IceStorm.sh BBB

Examples

BeagleWire software repository has a lot of different sources. The following description shows how to use it. Examples can be divided into two parts. The first part is the simplest examples which do not have their own subsystem in Linux kernel e.g. rotary excoder, ultrasonic ranger sensor or blink leds. In these examples we can connect with FPGA using write/read operations for /dev/mem file. The second part consists of examples with kernel driver e.g. SPI, GPIO.