Installation instructions

[hermanbanken]

For some reason, on my RPi 3 with newest golang (with module support) adding this lib as a dependency fails to build it.

I need to do this first:

# Get ws2811.h header & w2811 library (-lw2811)
sudo git clone https://github.com/jgarff/rpi_ws281x.git
cd rpi_ws281x
sudo scons deb
sudo dpkg --install libws2811_1.1.0-1.deb

[hermanbanken]

Also, the headers needed to made available.

It would be lovely if this would work Out of the Box™️, e.g. install golang Module and be done! That is the goal of this repo, right?

[supcik]

You are right. I should work on some INSTALL documentation. This project is actually a Go "wrapper" for the jgarff/rpi_ws281x library and this library must be compiled and made available to Go.

Currently I am using a Git sub-module in the vendor directory, but I have to document the process.

[hermanbanken]

I saw the submodule, but it doesn't work if 'rpi-ws281x/rpi-ws281x-go' is a module of another project, because go mod does not recursively checkout the submodule.

I actually got the compilation working (cross-compilation) using this dockerfile:

# Builder stage
FROM resin/armv7hf-debian AS builder

# Cross-building background info: https://www.balena.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/
RUN [ "cross-build-start" ]

# Get golang 1.11
RUN curl https://dl.google.com/go/go1.11.2.linux-armv6l.tar.gz --output golang.tar.gz && \
    sudo tar -C /usr/local -xzf golang.tar.gz && \
    rm golang.tar.gz

# Install apt deps
RUN sudo apt-get update && apt-get install git scons gcc libc-dev libasound2-dev

# Get ws2811 headers & w2811 library (-lw2811) available
RUN sudo git clone https://github.com/jgarff/rpi_ws281x.git && \
    cd rpi_ws281x && \
    sudo scons deb && \
    sudo dpkg --install libws2811_1.1.0-1.deb

WORKDIR /app
COPY go-slide /app/
RUN env GOOS=linux GOARCH=arm /usr/local/go/bin/go mod vendor
RUN env GOOS=linux GOARCH=arm CGO_CFLAGS="-I/rpi_ws281x" CGO_ENABLED=1 /usr/local/go/bin/go build -mod vendor -o app
RUN [ "cross-build-end" ]
CMD ["./app"]

# Runner stage
FROM resin/armv7hf-debian
RUN [ "cross-build-start" ]
RUN sudo apt-get update && apt-get install libasound2-dev
COPY --from=builder /rpi_ws281x/libws2811_1.1.0-1.deb /
RUN sudo dpkg --install libws2811_1.1.0-1.deb
COPY --from=builder /app/app /app
COPY go-slide /
RUN [ "cross-build-end" ]
CMD ["./app"]

It contains some extra stuff that you can probably skip for a 'guide':

• libasound2-dev as i wanted to play sounds
• go-slide references, which is my project's name

[hermanbanken]

NB: this is using Resin/Balena's images and I can build this on my Mac using that Docker file.

[supcik]

OK. I did not have to use a Docker image. You can see how I did in the rpi-ws281x-go/.circleci/config.yml file.

But it's good to know that you are cross-compiling and not trying to build on the RPi. I will write the install documentation for cross-compilation first.

[hermanbanken]

I did normal on-device compilation first. That also works, but obviously is a lot slower and in the end I want to use Balena. If everything compilation wise works as expected.

[supcik]

As far as I know, with the Balena image, the compilation runs in an ARM emulator (using QEMU). This is OK, but I think that the compilation is more efficient if "traditional" cross-compilation techniques are used. But perhaps my knowledge about Balena is no longer up-to-date.

[hermanbanken]

True! But the problem was that using a “normal” build ($GOARCH) I could not get https://github.com/faiface/beep working, so I needed the qemu (I think).

[supcik]

OK. I don't know about the "beep" package.

[supcik]

@hermanbanken, do you have any suggestion on how to improve the documentation ? What can I do to improve it ?

[hermanbanken]

Yes, at least I think some mention of checking out the submodule must be added somewhere: otherwise you can not use go mod & build this as a submodule of another project.

Another thing to document a bit more is the configuration. The wrapped library has a lot of options of which you also expose all/most, but if you're just looking for how to use this with Go you miss some essentials. A simple fix is to point people at the struct & its fields from the README, so they have a starting point for figuring out how it works.

[supcik]

OK, thank you. I will go in this direction.

[supcik]

I extended the documentation based on your suggestions. I removed the "vendor" directory because I am directly using the latest version of the C library. I will add CI/CD nightly builds to check the go wrapper against the C library.

Thank you again for your constructive feedback and please, let me know if I can close this issue or if you have further suggestions.

[hermanbanken]

Just took a look at the new readme: it looks very nice! Love it 😍