Paraphraser/Docker+OctoPrint - When your 3D printer turns on and off.md

## Docker+OctoPrint - When your 3D printer turns on and off.md

      
    Raw
  

              Docker+OctoPrint - When your 3D printer turns on and off.md
            
          
    octoprint-docker: when your 3D printer turns on and off


Task goals


Keep the OctoPrint Docker container service running even when your printer is switched off:

GCODE files can still be uploaded
Plugins can still be updated


React gracefully and appropriately to the 3D printer being switched on and off


Support camera streaming "following the printer" (this is optional).


Contents


Theory


About IOTstack


Special Notes


Implementation


step 1: device discovery


step 2: edit service definition


step 3: add s6 mjpg-streamer run file


step 4: add printerDidChange script


step 5: add Dockerfile


step 6: build OctoPrint image


step 7: disconnect your 3D printer


step 8: create UDEV rule set

option 1: generic rule set
option 2: specific rule set
option 3: named-printer rule set


step 9: connect your 3D printer


step 10: use your browser to connect to OctoPrint


step 11: tell OctoPrint your printer's name (optional): connect to OctoPrint OctoPrint


step 12: connect to your printer


Container maintenance


Working example

test - named-printer rule set
test - Raspberry Pi reboot
test - Raspberry Pi shutdown and power-up (printer on throughout)
test - shutdown, disconnect printer, power-up


Known issues


Theory

A Dynamic Device Management UDEV rule set matches on a 3D printer as it connects or disconnects over USB. Each event triggers a reaction script within the running OctoPrint container.
The container's service definition is augmented to give it read-only visibility of the Raspberry Pi's /dev directory. Because the reaction script running inside the container can see what is going on in /dev outside the container, it is in a position to compare "what the Raspberry Pi knows" with "what the container knows" and play follow the leader. If the printer device:

is present in the Raspberry Pi's /dev directory but is not present in the container's /dev directory, the script adds the named device to the container's /dev directory using the major and minor device numbers discovered from the Raspberry Pi's /dev directory. The container gains access to the dynamically-mapped printer via a device_cgroup_rule in its service definition.
is not present in the Raspberry Pi's /dev directory but is present in the container's /dev directory, the script removes the named device from the container's /dev directory.

The script restarts the OctoPrint process (not the container) whenever a printer device change occurs. The dynamic addition and removal of the 3D printer device, coupled with the process restart, stops the container from crashing when a 3D printer is switched off or disconnected.
Camera support is optional and is handled similarly, save that while the external and internal printer device names are assumed to be the same, the camera argument is assumed to be the external device name, with the internal device name obtained from the CAMERA_DEV environment variable.
Camera support is optional to give the user the choice of:

No camera support (ENABLE_MJPG_STREAMER=false)
Standard camera support (passing the camera device via a static devices: mapping)
Follow the printer camera support (a design goal of this gist).

Follow the printer camera support:


Activates or disables the streamer service as and when the printer device comes and goes. The camera is not constantly imaging a scene where nothing is happening.


Requires changes to the internal s6 mjpg-streamer run file:
/etc/services.d/mjpg-streamer/run

to avoid it looping whenever the 3D printer is disconnected and the dynamic camera device mapping goes away.


Needs a device_cgroup_rule to give the container access to the camera.


About IOTstack

The examples in here assume SensorsIot/IOTstack conventions.
It is not essential for you to clone IOTstack onto your Raspberry Pi to make use of these instructions. However, some understanding of IOTstack's conventions will help you make sense of what is going on so you can adapt the techniques to your own environment.
IOTstack is not a system or application that you "run". IOTstack is a framework plus a set of conventions for making it as easy as possible to run arbitrary collections of Docker containers.
This is the basic IOTstack folder structure:
~/IOTstack
├── .templates ❶
│   └── octoprint ❷
│       └── service.yml ❸
├── menu.sh ❹
├── docker-compose.yml ❺
└── volumes
    └── octoprint ❻
        ├── octoprint
        └── plugins

A clone of the IOTstack repository includes a collection of service definitions which are stored in named folders within the .templates directory ❶.
IOTstack comes with a basic menu system ❹. If you run the menu and choose OctoPrint, the resulting docker-compose.yml ❺ will contain:
version: '3.6'

services:
  octoprint:
    container_name: octoprint
    image: octoprint/octoprint
    restart: unless-stopped
    environment:
    - TZ=Etc/UTC
  # - ENABLE_MJPG_STREAMER=true
  # - MJPG_STREAMER_INPUT=-r 640x480 -f 10 -y
  # - CAMERA_DEV=/dev/video0
    ports:
    - "9980:80"
    devices:
    - /dev/ttyAMA0:/dev/ttyACM0
  # - /dev/video0:/dev/video0
    volumes:
    - ./volumes/octoprint:/octoprint

networks:

  default:
    driver: bridge
    ipam:
      driver: default

  nextcloud:
    driver: bridge
    internal: true
    ipam:
      driver: default
That is the assumed starting point for the rest of this gist.
If you are not familiar with IOTstack's conventions:


In the 9980:80 port mapping directive, the external port was chosen because it does not conflict with any other service definition in the .templates folder. There is nothing magical about 9980. You can use any external port number that meets your needs.


The OctoPrint container's persistent storage is at the path ./volumes/octoprint. The leading dot implies "the folder containing docker-compose.yml" so, in practice, this means the absolute path:
~/IOTstack/volumes/octoprint ❻

You do not have to follow this convention. You can place persistent storage anywhere on your Raspberry Pi.


The networks: line and all lines after that are for NextCloud support. You can omit all those lines if you never intend to use IOTstack to run NextCloud on your Raspberry Pi.


Special Notes

If you are a Windows user, please do not copy material from this gist, paste it into a Windows text editor, and then move the file to your Raspberry Pi. Unless you take precautions, Windows will add its CR+LF line endings and those extra CRs will stop things from working properly on your Raspberry Pi.

Implementation


step 1: device discovery


Disconnect your 3D printer from your Raspberry Pi, either by turning the printer off or by detaching its USB cable.


Run the command:
$ tail -f /var/log/messages


While observing the log output, connect your 3D printer to your Raspberry Pi, either by turning the printer on or by attaching its USB cable. You are interested in messages that look like this:
mmm dd hh:mm:ss mypi kernel: [423839.626522] cp210x x-x.x.x:x.x: device disconnected
mmm dd hh:mm:ss mypi kernel: [431265.973308] usb x-x.x.x: new full-speed USB device number 10 using dwc_otg
mmm dd hh:mm:ss mypi kernel: [431266.109418] usb x-x.x.x: New USB device found, idVendor=dead, idProduct=beef, bcdDevice= 1.00
mmm dd hh:mm:ss mypi kernel: [431266.109439] usb x-x.x.x: New USB device strings: Mfr=1, Product=2, SerialNumber=3
mmm dd hh:mm:ss mypi kernel: [431266.109456] usb x-x.x.x: Product: CP2102N USB to UART Bridge Controller
mmm dd hh:mm:ss mypi kernel: [431266.109471] usb x-x.x.x: Manufacturer: Silicon Labs
mmm dd hh:mm:ss mypi kernel: [431266.109486] usb x-x.x.x: SerialNumber: cafe80facefeed
mmm dd hh:mm:ss mypi kernel: [431266.110657] cp210x x-x.x.x:x.x: cp210x converter detected
mmm dd hh:mm:ss mypi kernel: [431266.119225] usb x-x.x.x: cp210x converter now attached to ttyUSB0

Record the critical information:


from:
 … New USB device found, idVendor=dead, idProduct=beef, bcdDevice= 1.00


«vendorID» = dead
«productID» = beef


from:
 … SerialNumber: cafe80facefeed


«serialNumber» = cafe80facefeed


from:
 … converter now attached to ttyUSB0


«device» = ttyUSB0


Terminate the tail command by pressing control+c.


Substitute «device» in the following command and then execute it:
$ ls -l /dev/«device»
Example:
$ ls -l /dev/ttyUSB0
crw-rw---- 1 root dialout 188,  0 mmm dd hh:mm /dev/ttyUSB0
From the output, record the printer's major device number:

«printerMajorDeviceNumber» = 188


If you have a camera attached, find it and list its device details. For example:
$ ls -l /dev/video0
crw-rw---- 1 root video 81, 7 mmm dd hh:mm /dev/video0
Record the camera's major device number:

«cameraMajorDeviceNumber» = 81


step 2: edit service definition

Use a text editor to open docker-compose.yml. Replace the OctoPrint service definition (from the menu run) with these lines:
  octoprint:
    container_name: octoprint
    build:
      context: ./.templates/octoprint/.
      args:
      - OCTOPRINT_BASE=octoprint/octoprint:latest
    restart: unless-stopped
    environment:
    - TZ=${TZ:-Etc/UTC}
    - ENABLE_MJPG_STREAMER=true
    - MJPG_STREAMER_INPUT=-r 640x480 -f 10 -y
    - CAMERA_DEV=/dev/video0
    ports:
    - "9980:80"
    device_cgroup_rules:
    - "c «printerMajorDeviceNumber»:* rw"
    - "c «cameraMajorDeviceNumber»:* rw"
    volumes:
    - ./volumes/octoprint:/octoprint
    - /dev:/host/dev:ro
Next, replace all the place-holders with the correct values:


Set your time-zone correctly. You can either"


replacing Etc/UTC with your country and city; or


create the file ~/IOTstack/.env with the relevant content. For example:
 $ cat ~/IOTstack/.env
 TZ=Australia/Sydney

The advantage of using .env is you can leave all service definitions at TZ=${TZ:-Etc/UTC} with the single entry in the .env file covering all containers.
Tip:

Do not surround timezone strings with quote marks.


Replace «printerMajorDeviceNumber» with the value determined during device discovery.


Replace «cameraMajorDeviceNumber» with the value determined during device discovery.


If you do not have a camera at all:


set ENABLE_MJPG_STREAMER=false


remove the line:
 - "c «cameraMajorDeviceNumber»:* rw"


If you have a camera but want it to be always on:


remove the line:
 - "c «cameraMajorDeviceNumber»:* rw"


add the lines:
 devices:
 - /dev/video0:/dev/video0
If necessary, adjust the left hand side of device map to be your actual camera device.


You can also tweak the camera settings. For example, I'm using this "widescreen" value for my Raspberry Pi ribbon camera:
- MJPG_STREAMER_INPUT=-r 1152x648 -f 10
Here's a completed example:
  octoprint:
    container_name: octoprint
    build:
      context: ./.templates/octoprint/.
      args:
      - OCTOPRINT_BASE=octoprint/octoprint:latest
    restart: unless-stopped
    environment:
    - TZ=Australia/Sydney
    - ENABLE_MJPG_STREAMER=true
    - MJPG_STREAMER_INPUT=-r 1152x648 -f 10
    - CAMERA_DEV=/dev/video0
    ports:
    - "9980:80"
    device_cgroup_rules:
    - "c 188:* rw"
    - "c 81:* rw"
    volumes:
    - ./volumes/octoprint:/octoprint
    - /dev:/host/dev:ro

step 3: add s6 mjpg-streamer run file

Add the script file below to the octoprint template folder ❷:


Path: ~/IOTstack/.templates/octoprint/etc_services.d_mjpg-streamer_run


Mode: 755


Ownership: pi:pi


Content:
 #!/usr/bin/with-contenv sh

 if [ -n "$MJPEG_STREAMER_INPUT" ]; then
   echo "Deprecation warning: the environment variable '\$MJPEG_STREAMER_INPUT' was renamed to '\$MJPG_STREAMER_INPUT'"

   MJPG_STREAMER_INPUT=$MJPEG_STREAMER_INPUT
 fi

 if ! expr "$MJPG_STREAMER_INPUT" : ".*\.so.*" > /dev/null; then
   MJPG_STREAMER_INPUT="input_uvc.so $MJPG_STREAMER_INPUT"
 fi

 # only exec the streamer if the (internal) camera device exists
 if [ -e "$CAMERA_DEV" ] ; then
   exec mjpg_streamer \
     -i "/usr/local/lib/mjpg-streamer/$MJPG_STREAMER_INPUT -d $CAMERA_DEV" \
     -o "/usr/local/lib/mjpg-streamer/output_http.so -w /usr/local/share/mjpg-streamer/www -p 8080"
 fi

 # arriving here means camera device not linked yet - take the service down
 s6-svc -d /var/run/s6/services/mjpg-streamer


The script above is a replacement for the default version that is supplied with the OctoPrint-docker image. It makes the exec mjpg_streamer conditional on whether the $CAMERA_DEV device exists inside the container. If the exec occurs, the script ends at that point. If the $CAMERA_DEV device does not exist, the service is taken down. This avoids it looping continually.
This script is only executed by the running container if ENABLE_MJPG_STREAMER=true. If that variable is false, the running container deletes this script entirely so that it never runs.

step 4: add printerDidChange script

Add the reaction script below to the OctoPrint template folder ❷:


Path: ~/IOTstack/.templates/octoprint/printerDidChange


Mode: 755


Ownership: pi:pi


Content:
 #!/usr/bin/with-contenv bash

 # support script re-naming
 SCRIPT=$(basename "$0")

 log() {

    # being run interactively?
    if [ "$(tty)" = "not a tty" ] ; then
       # no! use s6 logging
       echo "$1" | s6-log T n20 s50000 /octoprint/octoprint/logs/printerDidChange
    else
       # yes! fake it
       echo "$(date +"%Y-%m-%d %H:%M:%S"),$$ - $SCRIPT - $1"
    fi

 }

 # decode arguments
 case "$#" in

   2 )
     EXT_CAMERA_DEV=/host/dev/$(basename "$2")
     INT_CAMERA_DEV="$CAMERA_DEV"
     ;&

   1 )
     EXT_PRINTER_DEV=/host/dev/$(basename "$1")
     INT_PRINTER_DEV=/dev/$(basename "$1")
     ;;

   *)
     log "Usage: $SCRIPT printer {camera}"
     exit -1
     ;;

 esac

 # assumptions
 RESTART_OCTOPRINT=false
 SHOULD_ENABLE_CAMERA=false

 # does the external printer device exist?
 if [ -e "$EXT_PRINTER_DEV" ] ; then

    # yes! that means the camera should be on
    SHOULD_ENABLE_CAMERA=true

    # discover the external device attributes
    EXT_MAJOR=$(( 16#$(stat -L -c "%t" "$EXT_PRINTER_DEV") ))
    EXT_MINOR=$(( 16#$(stat -L -c "%T" "$EXT_PRINTER_DEV") ))

    # does the internal printer device exist?
    if [ -e "$INT_PRINTER_DEV" ] ; then

       # yes! discover its device attributes
       INT_MAJOR=$(( 16#$(stat -L -c "%t" "$EXT_PRINTER_DEV") ))
       INT_MINOR=$(( 16#$(stat -L -c "%T" "$EXT_PRINTER_DEV") ))

       # both exist - do they match?
       if [ "$EXT_MAJOR" = "$INT_MAJOR" -a "$EXT_MINOR" = "$INT_MINOR" ] ; then

          # yes! no need to do anything
          log "$INT_PRINTER_DEV already linked"

       else

          # no! mismatch - must re-link
          log "re-linking $INT_PRINTER_DEV"

          # unlink old
          unlink "$INT_PRINTER_DEV"
          
          # link new
          mknod "$INT_PRINTER_DEV" c "$EXT_MAJOR" "$EXT_MINOR"
          
          # remember to restart OctoPrint
          RESTART_OCTOPRINT=true

       fi

    else

       # no! simply link internal to external
       log "linking $INT_PRINTER_DEV"

       # link it
       mknod "$INT_PRINTER_DEV" c "$EXT_MAJOR" "$EXT_MINOR"

       # remember to restart OctoPrint
       RESTART_OCTOPRINT=true

    fi
    
 else

    # no! passed a non-existent external printer device
    log "$EXT_PRINTER_DEV does not exist"

    # does an internal printer device exist?
    if [ -e "$INT_PRINTER_DEV" ] ; then

       # yes! internal is now redundant
       log "unlinking $INT_PRINTER_DEV"

       # unlink it
       unlink "$INT_PRINTER_DEV"
       
       # remember to restart OctoPrint
       RESTART_OCTOPRINT=true

    fi
    
 fi

 # is the container set up to run the streamer?
 if $ENABLE_MJPG_STREAMER ; then

    # yes! should the streamer be active?
    if $SHOULD_ENABLE_CAMERA ; then

       # does the external camera device exist?
       if [ -e "$EXT_CAMERA_DEV" ] ; then

          # yes! discover its device attributes
          EXT_MAJOR=$(( 16#$(stat -L -c "%t" "$EXT_CAMERA_DEV") ))
          EXT_MINOR=$(( 16#$(stat -L -c "%T" "$EXT_CAMERA_DEV") ))

          # does the internal camera device exist?
          if [ -e "$INT_CAMERA_DEV" ] ; then

             # yes! discover its device attributes
             INT_MAJOR=$(( 16#$(stat -L -c "%t" "$INT_CAMERA_DEV") ))
             INT_MINOR=$(( 16#$(stat -L -c "%T" "$INT_CAMERA_DEV") ))

             # both exist - do they match?
             if [ "$EXT_MAJOR" = "$INT_MAJOR" -a "$EXT_MINOR" = "$INT_MINOR" ] ; then

                # yes! no need to do anything
                log "$INT_CAMERA_DEV already linked"

             else

                # no! mismatch - must re-link
                log "re-linking $INT_CAMERA_DEV"

                # unlink old
                unlink "$INT_CAMERA_DEV"

                # link new
                mknod "$INT_CAMERA_DEV" c "$EXT_MAJOR" "$EXT_MINOR"

                # restart the streaming service
                s6-svc -r /var/run/s6/services/mjpg-streamer

             fi

          else

             # no! simply link internal to external
             log "linking $INT_CAMERA_DEV"

             # link it
             mknod "$INT_CAMERA_DEV" c "$EXT_MAJOR" "$EXT_MINOR"

             # bring up the streaming service
             s6-svc -u /var/run/s6/services/mjpg-streamer

          fi

       else

          # no! passed a null or non-existent external camera device
          log "$EXT_CAMERA_DEV does not exist"

          # does the internal camera device exist?
          if [ -e "$INT_CAMERA_DEV" ] ; then

             # yes! internal is now redundant
             log "unlinking $INT_CAMERA_DEV"

             # unlink it
             unlink "$INT_CAMERA_DEV"

             # stop the streaming service
             s6-svc -d /var/run/s6/services/mjpg-streamer

          fi

       fi

    else

       # no! camera not required
       log "no printer, no shoes, no camera service"

       # is the internal camera device defined?
       if [ -e "$INT_CAMERA_DEV" ] ; then

          # yes! internal is now redundant
          log "disabling $INT_CAMERA_DEV"

          # unlink it
          unlink "$INT_CAMERA_DEV"

          # stop the streaming service
          s6-svc -d /var/run/s6/services/mjpg-streamer

       fi

    fi

 else

    log "ENABLE_MJPG_STREAMER disabled in docker-compose.yml"

 fi

 # should OctoPrint be restarted ?
 if $RESTART_OCTOPRINT ; then

    # yes!
    log "restarting OctoPrint service"

    # go do it
    s6-svc -r /var/run/s6/services/octoprint

 fi


This script can be called with at least one, and at most two, arguments:

the first argument is required and is the device name of the 3D printer, as known to the Raspberry Pi. This name is also assumed to be the device name inside the container.
the second argument is optional and is the device name of the camera, as known to the Raspberry Pi. If present, the $CAMERA_DEV environment variable is assumed to hold the camera device name inside the container.

Note:

The ;& at the end of the 2 ) argument case label is not a mistake. It is a "fall through" instruction, like a case statement in C without a break.


step 5: add Dockerfile

Add the Dockerfile below to the OctoPrint template folder ❷:


Path: ~/IOTstack/.templates/octoprint/Dockerfile


Mode: 644


Ownership: pi:pi


Content:
 # reference supported arguments
 ARG OCTOPRINT_BASE=octoprint/octoprint:latest

 # Download base image
 FROM $OCTOPRINT_BASE

 # re-reference supported arguments and copy to environment vars
 ARG OCTOPRINT_BASE
 ENV OCTOPRINT_BASE=${OCTOPRINT_BASE}

 # copy extra files to image
 COPY etc_services.d_mjpg-streamer_run /etc/services.d/mjpg-streamer/run
 COPY printerDidChange /usr/local/bin/printerDidChange

 # set container metadata
 LABEL com.github.SensorsIot.IOTstack.Dockerfile.based-on.version="${OCTOPRINT_BASE}"
 LABEL com.github.SensorsIot.IOTstack.Dockerfile.based-on.repo="https://github.com/OctoPrint/octoprint-docker"
 LABEL com.github.SensorsIot.IOTstack.Dockerfile.based-on.maintainer="chief@hackerhappyhour.com"

 # don't need these variables in the container
 ENV OCTOPRINT_BASE=

 # EOF


step 6: build OctoPrint image

Execute the following commands to build the local image and instantiate the OctoPrint container:
$ cd ~/IOTstack
$ docker-compose up --build -d octoprint
This is what happens:


docker-compose reads your docker-compose.yml file and looks for the octoprint service definition.


the build: clause in the service definition tells docker-compose to process the Dockerfile at:
~/IOTstack/.templates/octoprint/Dockerfile

You can also control the version of Octoprint by adjusting the OCTOPRINT_BASE directive. For example, to pin to version 1.8.7:
- OCTOPRINT_BASE=octoprint/octoprint:1.8.7


the FROM directive in the Dockerfile downloads the octoprint/octoprint base image, and then the two COPY directives copy the following files from the templates folder into the base image to form a local image:

s6 mjpg-streamer run file
printerDidChange script


The newly-built local image is instantiated to become the running container.


step 7: disconnect your 3D printer

Disconnect your 3D printer, either by turning the printer off or by detaching its USB cable.

step 8: create UDEV rule set

Three example rule set templates are provided below. You need to select one template, tailor it to your needs, and install it in the Raspberry Pi directory:
/etc/udev/rules.d/

Some guides recommend rebooting or taking other action to "activate" UDEV rules. I have never found that to be necessary on the Raspberry Pi. In my experience, any newly-added (or edited) file in the rules.d directory is always active immediately.

option 1: generic rule set

This rule set will match on anything that has the potential to be a 3D printer. That's any device which naturally mounts as either /dev/ttyUSBn or /dev/ttyACMn.
This rule set has the advantage of simplicity and one-size-fits-all but the potential disadvantage of confusing OctoPrint if a matching device is not actually a 3D printer.


Path: /etc/udev/rules.d/88-generic3DPrinter.rules


Mode: 644


Ownership: root:root


Content  (must be exactly one line):
 ACTION=="add|change|remove", SUBSYSTEM=="tty", KERNEL=="ttyUSB[0-9]|ttyACM[0-9]", RUN+="/usr/bin/docker exec octoprint printerDidChange %k video0"


Optional edit:

If you do not want the camera to follow the printer, remove video0 as the second argument to printerDidChange (the %k is the first argument).


If you choose this rule set and a real 3D printer does not mount inside the OctoPrint container, check the device's major number because a new device_cgroup_rules line may need to be added to the service definition.
Acknowledgements:

This rule set is based on rules-for-dynamic-usb-serial-support/71.
See also this helpful YouTube video.


option 2: specific rule set

This rule set matches on actual printer characteristics. The only time you are likely to encounter trouble is if you have two printers with identical vendor IDs, product IDs and serial numbers.


Path: /etc/udev/rules.d/88-specific3DPrinter.rules


Mode: 644


Ownership: root:root


Template  (must be exactly two lines):
 ACTION=="add|change" SUBSYSTEM=="tty", ATTRS{idVendor}=="«vendorID»", ATTRS{idProduct}=="«productID»", ATTRS{serial}=="«serialNumber»", RUN+="/usr/bin/docker exec octoprint printerDidChange %k video0"
 ACTION=="remove" SUBSYSTEM=="tty", ENV{ID_VENDOR_ID}=="«vendorID»", ENV{ID_MODEL_ID}=="«productID»", ENV{ID_SERIAL_SHORT}=="«serialNumber»", RUN+="/usr/bin/docker exec octoprint printerDidChange %k video0"


Required edits:


Replace the following template fields with the values determined during device discovery:

«vendorID»
«productID»
«serialNumber»


Optional edit:

If you do not want the camera to follow the printer, remove video0 as the second argument to printerDidChange (the %k is the first argument).


option 3: named-printer rule set

This rule set is essentially the same as 88-specificPrinter.rules, save that you can also associate a human-readable name with your printer.
The advantage of this approach is that your printer will always get the same device name. The disadvantage of this approach is that you also have to tell OctoPrint about the name (but you only need to do it once for each printer that you set up this way).
Assume your printer model is a "MasterDisasterPro" and that you want to use that as the human-readable device name (rather than ttyUSB0). The name you choose for your printer can be a mixture of upper- and lower-case letters, digits and hyphens but you should probably avoid any other characters. You should also avoid re-using any name which is likely to be found in /dev/.


Path: /etc/udev/rules.d/88-namedPrinter.rules


Mode: 644


Ownership: root:root


Template  (must be exactly two lines):
 ACTION=="add|change" SUBSYSTEM=="tty", ATTRS{idVendor}=="«vendorID»", ATTRS{idProduct}=="«productID»", ATTRS{serial}=="«serialNumber»", SYMLINK+="«humanName»", RUN+="/usr/bin/docker exec octoprint printerDidChange «humanName» video0"
 ACTION=="remove" SUBSYSTEM=="tty", ENV{ID_VENDOR_ID}=="«vendorID»", ENV{ID_MODEL_ID}=="«productID»", ENV{ID_SERIAL_SHORT}=="«serialNumber»", RUN+="/usr/bin/docker exec octoprint printerDidChange «humanName» video0"


Required edits:


Replace the following template fields with the values determined during device discovery:

«vendorID»
«productID»
«serialNumber»


Replace «humanName» with your chosen human-readable device name. In this example:

«humanName» = MasterDisasterPro


Optional edit:

If you do not want the camera to follow the printer, remove video0 as the second argument to printerDidChange. The «humanName» field is the first argument.


step 9: connect your 3D printer

Connect your 3D printer, either by turning the printer on or by attaching its USB cable.
The s6-log facility used by printerDidChange does not make its logging directory available to group and world. You should change the directory permissions to something a little more appropriate:
$ sudo chmod 755 ~/IOTstack/volumes/octoprint/octoprint/logs/printerDidChange
Check the printerDidChange log:
$ tail ~/IOTstack/volumes/octoprint/octoprint/logs/printerDidChange/current
Depending on the UDEV rule set you implemented and the options you chose, you should expect to see messages like the following:
yyyy-mm-dd hh:mm:ss.sss  linking /dev/«printerDeviceHere»
yyyy-mm-dd hh:mm:ss.sss  linking /dev/«optionalVideoDeviceHere»
yyyy-mm-dd hh:mm:ss.sss  restarting OctoPrint service

Both the existence of the log file and these messages are confirmation that the UDEV rule triggered printerDidChange within the container. You will need to go back and check your work if the log file does not exist or does not contain the expected messages.

step 10: use your browser to connect to OctoPrint

Use a browser to open a connection with the OctoPrint web UI on port 9980 (or whatever port you are using if you changed it).

step 11: tell OctoPrint your printer's name (optional)

If you chose 88-namedPrinter.rules and associated a human-readable name with your printer, you need to tell OctoPrint about the device name you gave to your printer.
You only need to do this once per printer. Thereafter, OctoPrint will sense the printer when it is online in the same way as it would for any /dev/ttyUSBn or /dev/ttyACMn device.
The steps are:


Click the  🔧  ("Settings") icon on the toolbar.


Choose "Serial Connection" in the left hand panel (the default).


Add your printer to the "Additional serial ports" field. For example:
 /dev/MasterDisasterPro


Click  Save .


Restart OctoPrint, either from the "System" menu on the toolbar, or from the command line by:
 $ docker exec octoprint s6-svc -r /var/run/s6/services/octoprint


step 12: connect to your printer

Choose your printer in the  Serial Port  popup menu, then click  Connect .

Container maintenance

If OctoPrint informs you that a new version has become available:
$ cd ~/IOTstack
$ docker-compose build --no-cache --pull octoprint
$ docker-compose up -d octoprint
$ docker system prune -f
In words:

Be in the right directory.
Force a fresh download of the base image from DockerHub, and build a new local image by re-running the Dockerfile.
Instantiate the newly-built local image as the running container.
Clean up the old image.

If your 3D printer is powered on and connected over USB while you do this, the newly-instantiated container will not be "in sync". You will either have to power-cycle or disconnect/reconnect your 3D printer's USB cable to bring the container "in sync".

Working example

The platform I am using to run octoprint/octoprint is:


4GB Raspberry Pi 4 Model B Rev 1.4.


Raspberry Pi "ribbon camera".


Full 64-bit Debian GNU/Linux 11 Bullseye, built using PiBuilder with ENABLE_PI_CAMERA=legacy.

Note: building your Raspberry Pi with PiBuilder installs IOTstack and all its dependencies as part of the process.


AnyCubic I3 Mega 3D printer.


Camera follows the 3D printer.


I have run this same setup on Buster. You can also use PiBuilder to construct a Buster system. In that situation, PiBuilder interprets ENABLE_PI_CAMERA=legacy as an instruction to enable the camera.
I have also run this on a Raspberry Pi 3B+ (Buster) but with mixed results. All the problems were due to power (not the power supply). The board itself couldn't deliver what even the beefiest power supply unit could provide. If you want to know more, see Checking your Raspberry Pi's view of its power supply.

test - named-printer rule set

Printer off. Confirm active rule-set:
$ ls /etc/udev/rules.d/88*.rules
/etc/udev/rules.d/88-AnyCubicI3Mega.rules
Watch the log (see also log permissions):
$ tail -f ~/IOTstack/volumes/octoprint/octoprint/logs/printerDidChange/current
Turn printer on:
yyyy-mm-dd hh:mm:ss.sss  linking /dev/AnyCubicI3Mega
yyyy-mm-dd hh:mm:ss.sss  linking /dev/video0
yyyy-mm-dd hh:mm:ss.sss  restarting OctoPrint service

Visual result:

Device appears in Serial Port popup as /dev/AnyCubicI3Mega.
Camera is enabled.
With Serial Port popup set to "Auto", clicking  Connect  connects to printer.

Turn printer off:
yyyy-mm-dd hh:mm:ss.sss  /host/dev/AnyCubicI3Mega does not exist
yyyy-mm-dd hh:mm:ss.sss  unlinking /dev/AnyCubicI3Mega
yyyy-mm-dd hh:mm:ss.sss  no printer, no shoes, no camera service
yyyy-mm-dd hh:mm:ss.sss  disabling /dev/video0
yyyy-mm-dd hh:mm:ss.sss  restarting OctoPrint service

Visual result:

Only option in Serial Port popup is Auto.
Camera is disabled.


test - Raspberry Pi reboot

Printer on. Confirm dynamic connection:
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
crw-r--r-- 1 root root 188, 0 mmm dd hh:mm /dev/AnyCubicI3Mega
crw-r--r-- 1 root root  81, 7 mmm dd hh:mm /dev/video0
Reboot. Wait for Raspberry Pi to come up. Re-connect via SSH. Check connection situation:
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
crw-r--r-- 1 root root 188, 0 mmm dd hh:mm /dev/AnyCubicI3Mega
crw-r--r-- 1 root root  81, 7 mmm dd hh:mm /dev/video0
Conclusion: dynamic device mapping across reboot handled correctly.

test - Raspberry Pi shutdown and power-up (printer on throughout)

Printer on. Confirm dynamic connection:
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
crw-r--r-- 1 root root 188, 0 mmm dd hh:mm /dev/AnyCubicI3Mega
crw-r--r-- 1 root root  81, 7 mmm dd hh:mm /dev/video0
Shutdown. Wait for Raspberry Pi to go quiescent. Remove power. Re-apply power. Re-connect via SSH. Check connection situation:
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
crw-r--r-- 1 root root 188, 0 mmm dd hh:mm /dev/AnyCubicI3Mega
crw-r--r-- 1 root root  81, 8 mmm dd hh:mm /dev/video0
Conclusion: dynamic device mapping across power-cycle handled correctly.

test - shutdown, disconnect printer, power-up

Printer on. Confirm dynamic connection:
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
crw-r--r-- 1 root root 188, 0 mmm dd hh:mm /dev/AnyCubicI3Mega
crw-r--r-- 1 root root  81, 8 mmm dd hh:mm /dev/video0
Shutdown. Wait for Raspberry Pi to go quiescent. Remove power. Disconnect printer. Re-apply power. Re-connect via SSH. Check connection situation.
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
ls: cannot access '/dev/AnyCubicI3Mega': No such file or directory
ls: cannot access '/dev/video0': No such file or directory
Reconnect printer. Re-check connection situation.
$ docker exec octoprint ls -l /dev/AnyCubicI3Mega /dev/video0
crw-r--r-- 1 root root 188, 0 mmm dd hh:mm /dev/AnyCubicI3Mega
crw-r--r-- 1 root root  81, 8 mmm dd hh:mm /dev/video0
Conclusion: It does not matter whether the printer is switched off before the Raspberry Pi shutdown, or vice versa, the container response is correct.

Known issues


container re-creation

Although testing suggests that this structure will survive Raspberry Pi reboots and shutdowns, there is no mechanism for forcing a newly-created container to synchronise with the actual state of the 3D printer. A container is "newly-created" when:

Its service definition changes in docker-compose.yml and an up is performed.
The local Dockerfile is changed and an up --build is performed.
A new base image is pulled from DockerHub and a new local image constructed by running the Dockerfile (build --no-cache --pull), followed by an up.
If the user stops and removes container, then does an up.
If the user takes the stack down then up again.

The simplest approach whenever there's a lack of synchronisation is to disconnect and re-connect the 3D printer. That triggers the UDEV rule and forces synchronisation.
See also Container maintenance.

docker-compose.yml version directive

The device_cgroup_rules: directive is sensitive to the version directive in your compose file. In theory, the version directive is deprecated. In theory. If you want everything to work properly you need:
version: '3.6'

docker-compose version

The device_cgroup_rules: directive is also sensitive to the version of docker-compose being used.
If you have just built your Pi using PiBuilder then both docker and docker-compose will be up-to-date.
Conversely, if you are trying to run the OctoPrint container on top of an existing system, you may run into problems which will have as their root cause how docker and docker-compose were installed originally, and how they have been maintained since.
If you are in this situation and you don't want to rebuild your system from scratch using PiBuilder, try following the instructions in maintaining docker + docker-compose.