Getting started
Updated: 2023-05-19
Download, install and use
1. Download
Download a binary release suitable for your system.
File | OS | Arch | Size |
---|---|---|---|
embeddedgo-1.18.9.2-darwin-amd64.tar.gz | macOS | x86-64 | 150MB |
embeddedgo-1.18.9.2-darwin-arm64.tar.gz | macOS | ARM64 | 147MB |
embeddedgo-1.18.9.2-linux-amd64.tar.gz | Linux | x86-64 | 148MB |
embeddedgo-1.18.9.2-linux-arm64.tar.gz | Linux | ARM64 | 142MB |
embeddedgo-1.18.9.2-windows-amd64.zip | Windows | x86-64 | 165MB |
2. Install
Optionally remove the previous Embedded Go instalation and any related changes in PATH.
Extract the archive you just downloaded.
Add the extracted directory to your PATH. In case of Linux and Mac you can run scripts/setup.sh
to do this.
3. Use
Embedded Go is a superset of the original Go so you can use it the same way as the original one both for embedded and system programming.
The main tool of the original Go toolchain is the go
command. Embedded Go obviously provides go
too. It works the same as the original one. However, Embedded Go provides also a thin wrapper over go
called emgo
. Using emgo instead of go gives several benefits but the two most important are:
-
Facilitate the use of Embedded Go for embedded programming in the presence of the original Go compiler used for system programming (different, more satable version, etc.).
-
Allow to customize some of the Embedded Go environment variables using a
build.cfg
file. It’s especially useful when you work at the same time on multiple projects for different embedded targets. You can still use environment variables to configure Embedded Go if you want but variables set inbuild.cfg
have priority.
4. Example (Linux)
Install
$ tar xf embeddedgo-1.18.9.2-linux-amd64.tar.gz
$ ls embeddedgo-1.18.9.2-linux-amd64
emgo go project_template scripts
Alter the PATH environment variable
$ embeddedgo-1.18.9.2-linux-amd64/scripts/setup.sh
Adding /home/test/embeddedgo-1.18.9.2-linux-amd64 to the PATH in the
folowing profile files:
/home/test/.profile
Changes take effect on next login. Please relogin.
Create a simple project for the STM32F4-DISCOVERY board
$ mkdir blinky
$ cp embeddedgo-1.18.9.2-linux-amd64/project_template/build.cfg blinky
$ cd blinky
$ emgo mod init blinky
go: creating new go.mod: module blinky
$ cat > main.go
package main
import (
"time"
"github.com/embeddedgo/stm32/devboard/f4-discovery/board/leds"
)
func main() {
for {
leds.Green.SetOff()
leds.Orange.SetOn()
time.Sleep(time.Second / 2)
leds.Orange.SetOff()
leds.Red.SetOn()
time.Sleep(time.Second / 2)
leds.Red.SetOff()
leds.Blue.SetOn()
time.Sleep(time.Second / 2)
leds.Blue.SetOff()
leds.Green.SetOn()
time.Sleep(time.Second / 2)
}
}
<Ctrl+D>
$
Compile
$ emgo build
main.go:6:2: no required module provides package github.com/embeddedgo/stm32/devboard/f4-discovery/board/leds; to add it:
go get github.com/embeddedgo/stm32/devboard/f4-discovery/board/leds
$ emgo get github.com/embeddedgo/stm32/devboard/f4-discovery/board/leds
go: downloading github.com/embeddedgo/stm32 v0.10.0
go: added github.com/embeddedgo/stm32 v0.10.0
$ emgo build
$ ls
blinky.elf build.cfg go.mod go.sum main.go
Program the board using OpenOCD
$ cat > load.sh
#!/bin/sh
TARGET=stm32f4x
RESET=srst_only
TRACECLKIN=168000000
. $(emgo env GOROOT)/../scripts/load-oocd.sh
<Ctrl+D>
$ chmod a+x load.sh
$ ./load.sh
Bus 003 Device 008: ID 0483:3748 STMicroelectronics ST-LINK/V2
Open On-Chip Debugger 0.11.0+dev-00685-g830d70bfc (2022-05-17-14:21)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
debug_level: 0
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
TARGET: stm32f4x.cpu - Not halted
$ ./load.sh
Bus 003 Device 009: ID 0483:3748 STMicroelectronics ST-LINK/V2
Open On-Chip Debugger 0.11.0+dev-00685-g830d70bfc (2022-05-17-14:21)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
debug_level: 0
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0803414c msp: 0x20000800
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0803414c msp: 0x20000800
** Programming Started **
** Programming Finished **
5. More examples
See example programs for various microcontrollers and development boards on Github: Kendryte, nRF52, STM32.
You can find the proper build settings for every supported MCU/board in the board examples subdirectory, eg: minipro-f405/examples/build.cfg.
Installing Embedded Go from source (Linux, Mac)
Make a directory for Embedded Go toolchain:
mkdir embeddedgo
cd embeddedgo
Download embeddedgo/patch, embeddedgo/tools and (optionally) embeddedgo/scripts repositories:
git clone https://github.com/embeddedgo/patch
git clone https://github.com/embeddedgo/tools
git clone https://github.com/embeddedgo/scripts
Download the Go compiler:
git clone https://go.googlesource.com/go
Select the latest supporetd Go release, apply the correct patch and build the Embedded Go toolchain (takes about 2 minutes):
cd go
git checkout go1.18.9
patch -p1 <../patch/go1.18.9-1
cd src
./make.bash
You can run all.bash
instead of make.bash
to run tests. More information about installing Go from source is available on the Go website.
The alternate (not recommended) way is to clone the embeddedgo/go repository. It contains the latest (unstable) version of the compiler.
git clone https://github.com/embeddedgo/go
cd go/src
./make.bash
Build the emgo
tool and move it to the root of the Embedded Go toolchain.
cd ../../tools/emgo
../../go/bin/go build
mv emgo ..
Add your embeddedgo
directory to the PATH:
export PATH=$PATH:/path/to/the/embeddedgo
Use emgo
instead of go
to interact with the Embedded Go toolchain. Emgo wraps the go command. It first looks for the Go tree in the directory where it’s installed and uses the go tool from it if found. Otherwise it uses exec.LookPath("go")
to find the go binary elsewhere.
More information
Read Embedded Go blog.
Ask questions on the Embedded Go user group or reddit.