search

Clon1998 / mobileraker_companion

Companion for mobileraker, enabling push notification.
MIT License
209 stars 12 forks source link

readme

mobileraker_companion

GitHub GitHub tag (latest by date) GitHub issues

GitHub all releases

Companion for Mobileraker, enabling push notification for Klipper using Moonraker.

Table of Contents

Supported Platforms

Mobileraker Companion was initially designed for use on a clean Klipper and Moonraker installation on Debian. Over time, it has evolved to extend support beyond Debian, enabling installation on various platforms, including those commonly used in Creality products.

Tested Platforms

The companion has undergone successful testing on the following platforms:

Experimental Platforms

Given that the companion is implemented as a Python script, there is potential for it to function on other platforms as well. However, it's important to note the following considerations:

[!WARNING] While the companion has shown success on tested platforms, its behavior on other systems may vary. Community contributions and feedback on different platforms are encouraged.

Companion - Prerequisites

The Mobileraker Companion is a standalone Python application designed to seamlessly connect with the Moonraker instance on your 3D printer. While it can be installed on any local network device, it is frequently installed directly on the printer itself for optimal integration.

Installation Requirements

Python Compatibility

The Companion was developed for Python 3.x. Please ensure that your system supports Python 3.x.

Python Package Dependencies

[!TIP] You can ignore this info if you are not planning on installing the companion manually. The installer, docker and kiauh will take care of that.

The required Python packages for the Companion are listed in the mobileraker-requirements.txt file.

Companion - Installation

Choose from several installation options for the Mobileraker Companion.

Using the Installer

The installer provides the most convenient method for installing Mobileraker, particularly suited for a seamless experience for most users. However, we recommend exploring the alternative installation methods based on your preferences and system requirements.

To utilize the installer, open your terminal and execute the following commands:

cd ~/
git clone https://github.com/Clon1998/mobileraker_companion.git
./mobileraker_companion/scripts/install.sh

Installation via Kiauh

Utilize the Klipper Installation And Update Helper (Kiauh) by dw-0 for an alternative installation method. Refer to the Kiauh documentation for detailed instructions.

Run the Companion in Docker

Run the Companion in a Docker container by creating a mobileraker.conf file and using the following commands:

docker run -d \
    --name mobileraker_companion \
    -v /path/to/mobileraker.conf:/opt/printer_data/config/mobileraker.conf \
    ghcr.io/clon1998/mobileraker_companion:latest

or via docker compose:

services:
  mobileraker_companion:
    image: ghcr.io/clon1998/mobileraker_companion:latest
    volumes:
    - /path/to/mobileraker.conf:/opt/printer_data/config/mobileraker.conf

[!WARNING] Adjust the paths in the volume mounts to point to your mobileraker.conf file.

Manual Installation

For a manual installation, follow these steps:

  1. Ensure Python 3.x is installed on your system.

  2. Install the Python dependencies listed in mobileraker-requirements.txt.

  3. Set up a Python virtual environment.

  4. Create a mobileraker.conf file.

  5. Run the companion script manually with the following options:

    • -l: Define the log location (folder or absolute path).

    • -c: Define the config location (absolute path).

Adjust the installation method based on your preferences and system requirements.

Companion - Multi-Printer

The Mobileraker Companion is designed to support multiple printers. If you are using a single host for multiple Klipper and Moonraker instances, you can run the installation script described in Using the Installer multiple times. The script will intelligently handle the update of the mobileraker.conf file.

Alternatively, you can manually edit the mobileraker.conf file to add a new [printer <Name>] section for each printer. Refer to the following section for detailed information about the configuration format.

Companion - Config

By default, you don't need to create a config file. However, if you want to use multiple printers with a single Companion instance, enforce logins via Moonraker, or modify the notification behavior, you can customize the configuration. Below is an overview of the available sections and configurations

[general]
language: en 
# !!! DEPRECATED. The app now syncs the app's language to the companion
# one of the supported languages defined in i18n.py#languages (de,en,...)
# !!! For users from the UK: entering 'uk' will resolve to Ukrainian language, not English. Use 'en' for English!
# Default: en
timezone: Europe/Berlin 
# correct timezone e.g. Europe/Berlin for Berlin time or US/Central. 
# For more values see https://gist.github.com/heyalexej/8bf688fd67d7199be4a1682b3eec7568
# Default: Tries to use system timezone
# Optional
eta_format: %%d.%%m.%%Y, %%H:%%M:%%S
# Format used for eta and adaptive_eta placeholder variables
# For available options see https://strftime.org/
# Note that you will have to escape the % char by using a 2nd one e.g.: %d/%m/%Y -> %%d/%%m/%%Y
# Default: %%d.%%m.%%Y, %%H:%%M:%%S
# Optional
include_snapshot: True
# !! SUPPORTER ONLY - This feature requires beeing a supporter of Mobileraker as of now!
# Include a snapshot of the webcam in any print status/progress update notifications
# Default: True
# Optional

# Add a [printer ...] section for every printer you want to add
[printer <NAME OF YOUR PRINTER: optional>]
moonraker_uri: ws://127.0.0.1:7125/websocket
# Define the uri to the moonraker instance.
# Default value: ws://127.0.0.1:7125/websocket
# Optional
moonraker_api_key: False
# Moonraker API key if force_logins or trusted clients is active!
# Default value: False
# Optional
snapshot_uri: http://127.0.0.1/webcam/?action=snapshot
# !! SUPPORTER ONLY - This feature requires beeing a supporter of Mobileraker as of now!
# The ABSOLUT url to the webcam, the companion should make a screenshot of. 
# Default: 
# Optional
snapshot_rotation: 0
# The rotation applied to the image. Valid values : 0, 90, 180, 270
# Default: 0
# Optional
ignore_filament_sensors:
# Comma separated list of filament sensors to ignore, ignored filament sensors do not trigger 
# a notification if they are triggered. This is useful if you have a filament sensor that is used
# in a MMU setup like ERCF.
# IMPORTANT, do not include the sensor type. E.g. if your sensor is configured
# like: [filament_switch_sensor printhead_sensor] add `printhead_sensor` to the list.
# Default: empty
# Optional

[!IMPORTANT] Please note that the configuration entry for the printer's Moonraker endpoint is moonraker_uri, not moonraker_url. It's a common mistake to confuse these two. Ensure you're using the correct key in your configuration.

The Companion searches for a Mobileraker.conf file in the following locations (in order of precedence):

  1. ~/Mobileraker.conf
  2. <mobileraker_companion DIR>/mobileraker.conf
  3. ~/printer_data/config/mobileraker.conf
  4. ~/klipper_config/mobileraker.conf

A single Companion instance can support multiple printers. To configure multiple printers, add more [printer ...] sections to your config. Here's an example of a multi-printer config: Example multi-printer config: 

[printer V2.1111]
moonraker_uri: ws://127.0.0.1:7125/websocket
# Define the uri to the moonraker instance.
# Default value: ws://127.0.0.1:7125/websocket
moonraker_api_key: False
# Moonraker API key if force_logins or trusted clients is active!

[printer Ratty]
moonraker_uri: ws://ratrig.home:7125/websocket
# Define the uri to the moonraker instance.
# Default value: ws://127.0.0.1:7125/websocket
moonraker_api_key: False
# Moonraker API key if force_logins is active!
ignore_filament_sensors: printhead_sensor, sensor_name2

[!NOTE] Please restart the system service to ensure the new config values are used. You can do this by running the following terminal command: 

sudo systemctl restart mobileraker.service

Moonraker - Update manager

In order to get moonrakers update manager working with the companion add the following section to your moonraker.conf. 

[update_manager mobileraker]
type: git_repo
path: ~/mobileraker_companion
origin: https://github.com/Clon1998/mobileraker_companion.git
primary_branch:main
managed_services: mobileraker
virtualenv: ~/mobileraker-env
requirements: scripts/mobileraker-requirements.txt
install_script: scripts/install.sh

[!IMPORTANT] This section is applicable to a default Klipper installation. If you're using a K1 or SonicPad, you may need to modify the virtualenv path accordingly.

Custom Notifications

Unlock the full potential of Mobileraker Companion with personalized notifications tailored to your needs.

To add custom notifications, refer to the comprehensive documentation available in Custom Notification. This guide provides detailed information, guiding you through the process of creating and optimizing custom notifications to suit your preferences and workflow.

Uninstall

To uninstall the companion, please run the following command:

cd ~/mobileraker_companion
./scripts/install.sh -uninstall

How It Works

Mobileraker Companion seamlessly connects to your 3D printer(s) and actively listens to the WebSocket for updates. Whenever the print status changes or a new M117 message is received, the companion triggers the process of constructing a new notification.

The workflow unfolds as follows:

  1. Notification Configuration Retrieval: The companion retrieves the notification configuration for all registered devices from Moonraker's database. Your device is automatically registered by the Mobileraker Android/IOS app, syncing the notification configs to your printer.

  2. Notification Construction: Based on the fetched notification configurations, the companion constructs the notification's title and content, ensuring relevance and accuracy.

  3. Notification Submission: The constructed notification is then submitted to the FCM (Firebase Cloud Messaging) Backend to be relayed to Apple's/Google's Push services for delivery.

Visualization of the Architecture

System Diagram

This visual representation illustrates the intricate architecture, showcasing how Mobileraker Companion orchestrates notifications in conjunction with your 3D printer.

Changelog

[v0.4.0] - 2023-08-26

[v0.3.0] - 2023-03-29

[v0.2.1] - 2022-07-07