BeamOS

A Raspberry Pi distribution for the Mr Beam Laser Cutters. It includes the OctoPrint host software for 3d printers out of the box and the MrBeamPlugin that extends OctoPrint to be used with the Mr Beam Laser Cutters.

This repository contains the source script to generate the distribution out of an existing Raspbian distro image.

This repository is a fork of OctoPi but is not maintained by or affiliated with the maintainers of that project. This is a project integral to the laser cutters produced by MrBeam and cannot be used for a 3D printer out of the box.

TODO: Add possibility to switch between tags, branches and python versions.

How to use it?

1. Unzip the image and install it to an sd card like any other Raspberry Pi image
2. Configure your WiFi by editing octopi-wpa-supplicant.txt on the root of the flashed card when using it like a thumb drive
3. Boot the Pi from the card
4. Access the MrBeam using it's name MrBeam-XXXX at the back of the device, the address should be mrbeam-xxxx.local. This name is generated using the RaspberryPi serial number

Features

• OctoPrint host software for 3d printers
• MrBeam Plugin for OctoPrint Modifies host software to work on the MrBeam lasecutter specifically
• Raspbian tweaked for maximum performance for printing out of the box
• mjpg-streamer with RaspiCam support for live viewing of prints and timelapse video creation.

Requirements

1. qemu-arm-static If not running on an RPi
2. CustomPiOS
3. Downloaded Raspbian image.
4. root privileges for chroot
5. Bash
6. git
7. sudo (the script itself calls it, running as root without sudo won't work)

Build BeamOS From within BeamOS / Raspbian / Debian / Ubuntu

BeamOS can be built from Debian, Ubuntu, Raspbian, or even BeamOS. Build requires about 2.5 GB of free space available. It is recommended to use a fast storage as the script decompresses the .zip file of raspbian every time.

You can build it by issuing the following commands:

sudo apt-get install gawk util-linux qemu-user-static git p7zip-full python3

git clone https://github.com/guysoft/CustomPiOS.git
git clone https://github.com/mrbeam/BeamOS.git
cd BeamOS/src/image
wget -c --trust-server-names 'https://downloads.raspberrypi.org/raspios_lite_armhf_latest'
cd ..
../../CustomPiOS/src/update-custompios-paths
sudo modprobe loop
sudo bash -x ./build_dist beamos

Building BeamOS Variants

BeamOS supports building variants, which are builds with changes from the main release build. An example and other variants are available in CustomPiOS, folder src/variants/example.

By default it only builds a slightly different version of vanilla OctoPi. Give it the beamos variant to build the normal BeamOS.

docker exec -it mydistro_builder:

sudo docker exec -it mydistro_builder build [Variant]

Or to build a variant inside a container:

sudo bash -x ./build_dist [Variant]

Building BeamOS Flavors

Flavors are simply extra config tweaking on the base variant. I the case of BeamOS, it allows to build a develop flavor and/or a pre-filled device series for the MrBeam (2S, 2T, 2U ...)

sudo bash -x ./build_dist beamos [Flavor]

Or to make a develop image that automatically takes on the 2S variant:

sudo bash -x ./build_dist beamos develop 2S

Building Using Docker

See Building with docker entry in wiki

Usage

1. If needed, override existing config settings by creating a new file src/config.local. You can override all settings found in src/modules/beamos/config. If you need to override the path to the Raspbian image to use for building BeamOS, override the path to be used in ZIP_IMG. By default the most recent file matching *-raspbian.zip found in src/image will be used.
2. Run src/build_dist as root.
3. The final image will be created at the src/workspace

Development

All the scripts are written in Bash - not POSIX.

How it works

The collections of scripts work with a set of "modules". When no modules are provided, the script only creates an updated Raspbian image with limited changes (username, hostname, network setup ...). For more info around the modules, have a look at the Modules wiki for CustomPiOS

The scripts will do the following (abridged):

1. unzip the raspbian image from the provided .zip in src/image/ or src/image-raspios_lite_arm64/ into the image/ folder and mount it

2. for each module:

   1. cd modules/<module>/
   2. Collect and export the configuration variables from the config, config.local and config.flavour
   3. Mount the filesystem/ folder on the image root folder /
   4. Change root (chroot) to the mounted image.
   5. Run the start_chroot_script shell/bash script
   6. Optionaly run a nested module here (will unmount the filesystem and exit/reenter chroot in the process)
   7. Run the stop_chroot_script shell/bash script
   8. exit chroot

3. The end result image is in workspace/ or workspace-[variant]/ folder, ready to be dd'ed onto an SD card.

NOTE: All the scripts on the chroot will be run as the local root user.

Secrets

This repository is public, but it uses GitHub secrets to pull from proprietary sources and include authentication keys. You can find the GitHub secrets in the project settings

Private repos included in BeamOS

Because of complications when using actions/checkout, the proprietary projects have been added to the beamos module filesystem as git submodules. Their commit hash needs to be updated as part of this git repo:

git submodule sync
git foreach "git pull"
git add src/modules/beamos/filesystem/repos
git commit -m "Update X Y Z package"

These repos are

• IOBeam handles most IO components
• MrB Hardware Info Provides additional readings for IOBeam

• Mount Manager to run signed scripts when plugging in a usb stick

  • branch: mrbeam2-stable

• MrB Check Automated QA control script for the assembly of the MrBeam

  • branch: beamos

N.B. These repos are NOT affected by the branch written in the config files for building BeamOS.

Public MrBeam projects included in BeamOS

All the open source repos are pulled using the latest stable release tag or branch

• MrBeamPlugin The main plugin that drives the lasercutter
• Netconnectd The networking server that handles wifi and access point modes
• OctoPrint-Netconnectd The OctoPrint plugin that interfaces with Netconnectd
• Find My MrBeam OctoPrint plugin that sends network discovery data

• OctoPrint-Camera A camera plugin used for the QA testing (as of writing this)

  • branch : master

• LED strips server state-based LED strip driver

• Shield flash tool updates the microcontroller with our latest GRBL version

  • branch : mrbeam2-stable

• RPI_WS281X (discontinued) an LED strip driver used with the LED server

  • Uses the latest Python3 package from the upstream RPI_WS281X

• MrBeam Docs The documentation for using your MrBeam - offline

N.B. The listed branches can change with the "flavours" that you decide to build. For example, you could build a beta or alpha flavour that includes the mrbeam2-beta branches from the public repos. Private repos need to be changed and committed manually.

Automated Deployment

Every push to this repo will trigger a GitHub Action.

2 images will be built:

• Stable version YYYY-MM-DD-beamos-2S-$DIST_VERSION.img - it should be used when assembling new devices of the 2S variant
• Develop version YYYY-MM-DD-beamos-develop-2S-$DIST_VERSION.img - Predefined develop account, options and settings; should be just "plug-n-play" except for the camera calibration

These images are compressed and uploaded to an S3 storage defined in build.yml and the base64 encoded credentials are provided as a secret. See internal documentation to access these builds.

Alpha Image Release

If you have access to the project, you can trigger a build for an alpha version image in the GitHub Actions using Build image > Run workflow > Alpha build true/false default: false : true

Making a new release

1. Update the private submodules
2. If a submodule was updated, be sure to commit the commit hash change.
3. Once pushed, a new build will run with a Github automation
4. After testing the result of the uploaded image, create a new release
5. Be sure to attach the .zip file to publish the image with the release.