Skip to content

Latest commit

 

History

History
236 lines (157 loc) · 9.5 KB

README.md

File metadata and controls

236 lines (157 loc) · 9.5 KB
Raw
layout title nav_order description wcversion tags
default
Home
1
Help pages for WebControl
0.915.001
web-control

WebControl

The official tool for Maslow CNC; control your Maslow with any web browser.

  • Browser-based, multi-platform controller software.
  • Connects to Maslow's Arduino Mega (or similar) via USB.
  • Includes setup instructions (updated from Maslow Community Garden).
  • Runs gcode (.nc files) for printing cuts.

You can report issues to the volunteer team.

Context

WebControl started as a browser-based port of the original GroundControl application, but has grown to support more features:

  • The calibration and setup process is better documented and easier to use.
  • It implements a flask+socketio web server, so other computers on the network may control the machine.
  • It can be run on a low-cost device, like a Raspberry Pi.
  • It can also support multiple custom firmwares developed by the community which enhance the Maslow.

At this point, WebControl has become the de-facto beginner's tool for Maslow.

Screenshot

Installation

Pre-Built Raspberry Pi Image

See the dedicated repository.

Raspberry Pi

Replace the version number with the latest release...

cd ~
mkdir webcontrol
cd webcontrol
wget https://github.com/WebControlCNC/WebControl/releases/download/v0.920/webcontrol-0.920-rpi-singledirectory.tar.gz
tar -zxvf webcontrol-0.920-rpi-singledirectory.tar.gz

Linux (Debian)

Replace the version number with the latest release...

cd ~</br>
mkdir webcontrol
cd webcontrol
wget https://github.com/WebControlCNC/WebControl/releases/download/v0.920/webcontrol-0.920-linux-singledirectory.tar.gz
tar -zxvf webcontrol-0.920-linux-singledirectory.tar.gz

Linux Autostart (systemd)

To run WebControl automatically on startup for a Linux-based machine, it is recommended to create a service:

nano webcontrol.service

type the following:

[Unit]
Description=WebControl
After=network.target

[Service]
ExecStart=/home/pi/webcontrol/webcontrol
WorkingDirectory=/home/pi/webcontrol
StandardOutput=inherit
StandardError=inherit
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

Save file using Ctrl-X/Yes

sudo cp webcontrol.service /etc/systemd/system

Test with the following:

sudo systemctl start webcontrol.service

Try to reach webcontrol using your browser.

To debug, try:

sudo systemctl status webcontrol

Or, to. get logs:

journalctl -xe

When it works, then type:

sudo systemctl enable webcontrol.service

see for more details: https://www.raspberrypi.org/documentation/linux/usage/systemd.md

Docker & Kubernetes

  • Pull the docker image from inzania/web-control using the armv7 or amd64 tag.
  • Mount a data/config volume at /root/.WebControl
  • Expose port 5000
  • Run with privileged: true security context for USB access.

Remote Access

WebControl can be run behind a front-proxy with TLS termination, such as nginx. You can use this in conjunction with semi-static IP to access your Maslow from anywhere with internet access. The full scope of this is outside this documentation, so you should be sure you understand the security implications before proceeding (hint: WebControl doesn't have a login or user authentication system).

Usage

Open your web browser to localhost:5000 (or use the IP address of your device).

Built With

  • Flask - The web framework used
  • Flask-Socketio - Websocket integration for communications with browser clients
  • Bootstrap4 - Front-end component library
  • Jinja2 - Template engine for web page generation
  • Feather.js - Only icon library I could find that had diagonal arrows.. works well to boot.
  • OpenCV - Library for computer vision to implement optical calibration
  • Numpy - Library for math routines used with optical calibration
  • Scipy - Another library for math routines used with optical calibration
  • Imutils - Adrian Rosebrock's library used with optical calibration
  • Schedule - Library used to schedule checking connection with arduino
  • Ground Control - Much of this was adapted from the Kivy-based Ground Control

Developing

Python Virtual Environment

There are several ways to set up a Python virtual environment (sometimes shown as 'virtualenv' or just 'venv'). Python itself can do this with the command python -m venv venv to create a virtual environment called venv. However, it's quite common to work with multiple versions of Python itself, so having a tool that can manage multiple Python versions and virtual environments is really helpful.

To manage multiple python versions and virtual environments get pyenv (or pyenv-win for Windows)

Here's a well-written walkthrough of setting up your system (macOS, Ubuntu/Debian, Fedora/CentOS/RHEL, Windows) for pyenv and then using pyenv to set up your virtual environment.

Once you've prepared your system and installed pyenv

  • get the latest version of Python that we know works with WebControl, currently that's 3.9.13: pyenv install 3.9.13
  • create a virtual environment with it: pyenv virtualenv 3.9.13 webcontrol_3_9 The webcontrol_3_9 name is arbitrary
  • activate the virtual environment - this will help isolate what you do from the rest of your system: pyenv activate webcontrol_3_9

Prepare the Virtual Environment itself

This next stuff should only need to be done once in your virtual environment.

  • install some useful tools pip install setuptools pip install pip-tools pip install black
  • rebuild the list of requirements needed by WebControl (optional) rm requirements.txt pip-compile -r requirements.in --resolver=backtracking --verbose
  • install the requirements pip install -r requirements.txt

And that's the virtual environment creation and set up done. From now on you'll only need to activate the virtual environment after any restart to get going.

Virtualenv on a Raspberry Pi

When running on the Pi, you'll also need some extra dependencies and will need to build OpenCV from source. See the Dockerfile for details. (TODO: add instructions here)

Now What? Let's Start Up WebControl🎉

Then you can run the code with.

python main.py

The server will then be available at http://localhost:5000

  • If you get an error message with something like ModuleNotFoundError: No module named '_ctypes' within it. Then it means that you didn't get your system properly prepared before creating your virtual environment (looking at you Ubuntu). Please follow the walkthrough linked above to:
  1. deactivate your virtual environment,
  2. delete it,
  3. prepare your system,
  4. recreate your virtual environment.

Automatic code formatting

This project uses black to automatically format python code. To run the autoformatter, simply install black locally with pip.

pip install black

Subsequently, you can just run black . to format all files in the current directory.

black .

If you don't have python3.6+ locally (to be able to run black), you can run black in a Docker container.

docker run -v $(pwd):/code johnboiles/python-black .

IDE

PyCharm

Pycharm Community Edition is a free, well-featured Python IDE.

With the File Watchers and BlackPycharm plugins you can set up your editor to automatically format your code on save. Then you never have to think about code formatting again 🎉

VSCode

Visual Studio Code is a free IDE with awesome support for Python (and every other language you can think of). And yes, you can install it on a Raspberry Pi.

Once it picks up that you're working with Python it will advise on extensions that are available to help you get the best out of it, including Python, PyLance, Black, ... Plus built-in support for GitHub, extensions for Docker, Linux under Windows (WSL), and so much more

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

Added to TODO list?

With Thanks

See also the list of contributors who participated in this project.

License

See LICENSE