diff --git a/bin/build-service.sh b/bin/build-service.sh index d1c9ef017..24887d443 100755 --- a/bin/build-service.sh +++ b/bin/build-service.sh @@ -1,6 +1,12 @@ #!/bin/bash un="$2" -port="$3" + +# Startup options (prepended to launch command), i.e., "export MAKERVERSE_PORT=80" +cmd_opts="" +if [[ ! -z "$3" ]]; then + cmd_opts="$3 && " +fi + echo "Makerverse Server will be controlled by $un" sv="makerverse.service" @@ -40,10 +46,7 @@ if [ "$1" = "install" ]; then echo "" >> $sf echo "[Service]" >> $sf - if [[ ! -z "$port" ]]; then - echo "Environment=MAKERVERSE_PORT=${port}" - fi - echo "ExecStart=runuser -l ${un} -c \"${lf}\"" >> $sf + echo "ExecStart=runuser -l ${un} -c \"${cmd_opts}${lf}\"" >> $sf echo "Restart=always" >> $sf echo "StandardOutput=syslog" >> $sf echo "StandardError=syslog" >> $sf diff --git a/ci/raspbian-desktop.json b/ci/raspbian-desktop.json index 1e6c4b254..8e8eb5a9c 100644 --- a/ci/raspbian-desktop.json +++ b/ci/raspbian-desktop.json @@ -86,7 +86,7 @@ "sudo usermod -aG docker pi", "sudo systemctl enable docker", "sudo systemctl start docker", - "cd /home/pi/makerverse && bash bin/build-service.sh install pi" + "cd /home/pi/makerverse && bash bin/build-service.sh install pi 80" ] } ] diff --git a/ci/raspbian-lite.json b/ci/raspbian-lite.json index 293a0b5fa..c1bd033db 100644 --- a/ci/raspbian-lite.json +++ b/ci/raspbian-lite.json @@ -79,7 +79,7 @@ "sudo usermod -aG docker pi", "sudo systemctl enable docker", "sudo systemctl start docker", - "cd /home/pi/makerverse && bash bin/build-service.sh install pi" + "cd /home/pi/makerverse && bash bin/build-service.sh install pi \"export MAKERVERSE_PORT=80\"" ] } ] diff --git a/docs/about/contribution.md b/docs/about/contribution.md index bc6e0b604..623909685 100644 --- a/docs/about/contribution.md +++ b/docs/about/contribution.md @@ -11,9 +11,11 @@ Pull requests welcome! See [issues](/about/#issues) for reporting bugs or problems. -## Documentation +## Updating the Documentation -These docs are located within the same Github repository that is home to Makerverse. You'll find them in the `docs/` folder, stored as `.md` (markdown) files. Therefore, the contribution process is the same as changing the Makerverse code... +These docs are located within the same Github repository that is home to Makerverse. You'll find them in the `docs/` folder, stored as `.md` (markdown) files. Therefore, the contribution process is the same as changing the Makerverse code (_see below_). Once a pull request containing docs has been approved and merged, it will appear automatically on Makerverse.com. + +_**Note**: to test your changes to the docs, run `bundle exec jekyll serve` from the `docs/` folder. You will need to have Ruby & Jekyll installed ([see their docs](https://jekyllrb.com/docs/installation/))._ ## How to Contribute diff --git a/docs/features/advanced.md b/docs/features/advanced.md index 960f91206..c309eda50 100644 --- a/docs/features/advanced.md +++ b/docs/features/advanced.md @@ -2,11 +2,15 @@ layout: default title: Advanced parent: Features -nav_order: 10 +nav_order: 9 --- # Advanced ## Turn Off Login (Guest Mode) -To enable guest mode, edit the `~/.makerverse` to include the top-level `insecureDangerousGuestAccess` boolean key. + In [extreme cases](/features/security/#security-hazards) this may result in a **risk to your physical safety**!! + +_Edit the `~/.makerverse` to include the top-level `insecureDangerousGuestAccess` boolean key._ + +In keeping with Makerverse's "easier to be secure" philosophy, guests are required to bypass the login screen at regular intervals (whereas logged-in users stay logged in). diff --git a/docs/features/index.md b/docs/features/index.md index 0dd1d4b4c..40f104c95 100644 --- a/docs/features/index.md +++ b/docs/features/index.md @@ -2,7 +2,7 @@ layout: default title: Features permalink: /features/ -nav_order: 3 +nav_order: 4 has_children: true --- diff --git a/docs/features/security.md b/docs/features/security.md index 341eab8d3..30e6a6719 100644 --- a/docs/features/security.md +++ b/docs/features/security.md @@ -2,7 +2,7 @@ layout: default title: Security parent: Features -nav_order: 9 +nav_order: 8 --- # Security @@ -21,8 +21,20 @@ When you first install Makerverse and log in to your account, an internet connec If at any point you become locked out of your account, you can reset your password using the email address you used to create the account. -## Detailed Explanation +## Potential Safety Hazards -There's a good blog post by the folks at Octoprint about [why accounts are needed for security purposes](https://octoprint.org/blog/2018/09/03/safe-remote-access/). The blog post notes that [security researchers have found](https://isc.sans.edu/forums/diary/3D+Printers+in+The+Wild+What+Can+Go+Wrong/24044/) _thousands of exposed (hackable) OctoPrint installations_. The blog post doesn't discuss public (or poorly-secured) networks, but there are doubtlessly **many times more** installations vulnerable to hacking along this attack vector. +Though it may sound extreme, accounts are meant to protect against potential safety hazards. -To prevent this from ever becoming a problem with Makerverse, we made the decision to require secure login from the very beginning. Using a centralized authority (OpenWorkShop) allows authentication to happen via HTTPS (encrypted channels). Unlike with a "local-login," _your password is never transmitted via HTTP_. Moreover, OpenWorkShop uses modern security best-practices (OAuth, as opposed to a simple username/password) and open-source security libraries (`oidc-client`). This means that even someone who has hacked your WiFi network will be unable to see your login credentials. +Makerverse can run large-scale heavy CNC machinery, laser cutters, plasma torches, and more. Many users enable full remote control over these tools, including the ability to turn them on and off via a web browser. It would be entirely possible for an uninformed guest to cause accidental human harm with such tools. Thus, accounts ensure that even well-intentioned guests cannot use the system. + +## Technical Explanation + +There's a good blog post by the folks at Octoprint about [why accounts are needed for security purposes](https://octoprint.org/blog/2018/09/03/safe-remote-access/). The blog post notes that [security researchers have found](https://isc.sans.edu/forums/diary/3D+Printers+in+The+Wild+What+Can+Go+Wrong/24044/) _thousands of totally exposed ("don't even need to hack them") OctoPrint installations_. The blog post doesn't discuss public (or poorly-secured) networks, but there are doubtlessly **many times more** installations vulnerable to hacking along this attack vector. + +_**Note**: despite the above security report, the folks behind OctoPrint are extremely diligent in this matter. We simply feel that a tool like Makerverse, which comes with the above hazards, should make it **easier** to be secure than insecure._ + +## Philosophy + +To prevent this from ever becoming a problem with Makerverse, we made the decision to be "secure by default." Using a centralized authority (OpenWorkShop) allows authentication to happen via HTTPS (encrypted channels). Unlike with a "local-login," _your password is never transmitted via HTTP_. Moreover, OpenWorkShop uses modern security best-practices (OAuth, as opposed to a simple username/password) and open-source security libraries (`oidc-client`). This means that even someone who has hacked your WiFi network will be unable to see your login credentials. + +If you still want to enable guest mode, despite the potential hazards, see the "advanced" features. diff --git a/docs/index.md b/docs/index.md index 2e261847f..58026d21b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,6 @@ A full-featured web-based controller platform for CNC & 3DP machines. ## Quickstart - Follow the [installation](/installation/) guide. +- [Connect to the application](/tutorial/open-makerverse/) and [create a workspace](/tutorial/create-workspace/). - Follow your [machine-specific](/machines/) instructions. -- Launch the application and create a workspace (_coming soon_). -- Calibrate and test your machine (_coming soon_). -- Run your first print/cut (_coming soon_). +- Upload and [run your first cut or print](/tutorial/run-programs/). \ No newline at end of file diff --git a/docs/installation/index.md b/docs/installation/index.md index dd04d1ed0..5874fc3b6 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -6,12 +6,22 @@ permalink: /installation/ has_children: true --- +# Installation + You can always find the latest versions on the [Releases page](https://github.com/makermadecnc/makerverse/releases/). +## Methods + There are **two primary ways** to run Makerverse. -- **Stand-Alone**: easy to install on Mac and Windows, but can only be used from that computer. -- **Web Server**: works on any computer; can be accessed from any web browser. +- **Stand-Alone**: easy to install on Mac and Windows; harder to update. +- **Web Server**: works on any computer; has automatic updates. + +## Recommendations + +1. If you have a Raspberry Pi, just [flash the pre-built image](/installation/web-server/raspberry-pi/) for the easiest, most full-featured solution. +2. If you're **non-technical** and **only** using Makerverse on a **Mac/Windows** computer, use the [stand-alone install](/installation/stand-alone/). +3. Otherwise, use the [generic web server install](/installation/web-server/) (works with just about any computer). ## Prereleases (Beta Versions) diff --git a/docs/installation/web-server/docker.md b/docs/installation/web-server/docker.md index 1111697b5..95a55261f 100644 --- a/docs/installation/web-server/docker.md +++ b/docs/installation/web-server/docker.md @@ -75,6 +75,15 @@ docker run --rm --privileged --name makerverse \ "makerverse/core:latest" ``` +## Configuration + +You can set the following environment variables to configure Makerverse on any Web Server: + +- `MAKERVERSE_PORT`: Which port to listen on (default: `8000`). +- `MAKERVERSE_HOME`: Where the settings files should be stored (default: `$HOME`). +- `MAKERVERSE_SRC_DIR`: Where the Makerverse code is located (default: `$HOME/makerverse`). +- `MAKERVERSE_LAUNCH_METHOD`: Use Docker or Node? (default: `docker`). + ## Updating Each time the `bin/launch` script is run, it will automatically update the application by pulling the latest docker image. If you use the [linux service](/installation/web-server/linux-service/#updating), this happens each time you restart the service. diff --git a/docs/installation/web-server/index.md b/docs/installation/web-server/index.md index 0bddc4ae6..c5cd41a3a 100644 --- a/docs/installation/web-server/index.md +++ b/docs/installation/web-server/index.md @@ -14,21 +14,12 @@ _**Tip**: the easiest setup is the [Raspberry Pi Image](/installation/web-server If you don't wish to use the pre-built image, you can achieve the same thing on a Raspberry Pi (or any Debian computer) using the [Linux Service](/installation/web-server/linux-service/) installation. For all other cases, refer directly to the [Docker](/installation/web-server/docker/) instructions. -## Configuration - -You can set the following environment variables to configure Makerverse on any Web Server: - -- `MAKERVERSE_PORT`: Which port to listen on (default: `8000`). -- `MAKERVERSE_HOME`: Where the settings files should be stored (default: `$HOME`). -- `MAKERVERSE_SRC_DIR`: Where the Makerverse code is located (default: `$HOME/makerverse`). -- `MAKERVERSE_LAUNCH_METHOD`: Use Docker or Node? (default: `docker`). - ## Updating The web server installation automatically updates when it restarts. -To update a web-server install, just run the `bin/launch` script: +To manually update a **Linux Service** install, use `sudo systemctl restart makerverse`. + +_**Note**: while the update is downloaded, Makerverse will continue to run the old installation. You can check on the update progress with `journalctl -xe`. Once the update is complete, refresh your internet browser and look at the "About" screen to confirm the new version._ -``` -$HOME/makerverse/bin/launch -``` +To manually update a Docker install (without a Linux service), run `bin/launch` from within the Makerverse directory. This can also be useful if you would like more feedback on the update progress (this approach happens in the foreground, instead of requiring that you use the `journalctl` command to view logs). diff --git a/docs/installation/web-server/linux-service.md b/docs/installation/web-server/linux-service.md index ff4a2962e..f2fa07593 100644 --- a/docs/installation/web-server/linux-service.md +++ b/docs/installation/web-server/linux-service.md @@ -29,6 +29,17 @@ Type `sudo systemctl [command] makerverse`, replacing **[command]** with one of - `stop`: Stop the application. - `disable`: Do not start the application automatically. +## Configuration + +If you would like to set one or more [configuration (environment) variables](/installation/web-server/docker/#configuration), you will need to pass them to the service. For example, to set the port to 80 (_which is done by default on the Raspberry Pi image_), **reinstall the service** as follows (from the Makerverse directory): + +``` +sudo bin/build-service.sh install $(whoami) "export MAKERVERSE_PORT=80" +``` + +- The second parameter is the username (e.g., `pi`) which will run the service. +- The third parameter will be prepended to the start command, in this case exporting the environment variable. + ## Troubleshooting The following commands are helpful if something is not working: diff --git a/docs/installation/web-server/raspberry-pi.md b/docs/installation/web-server/raspberry-pi.md index 3819c53f1..5781038c8 100644 --- a/docs/installation/web-server/raspberry-pi.md +++ b/docs/installation/web-server/raspberry-pi.md @@ -14,10 +14,18 @@ It does all the work of setting up the Docker environment (and Linux service) fo ## Requirements -- Raspberry Pi 3B+ (or better) -- 16 GB micro SD card (or bigger) -- Power supply for the RPi -- _Optional: keyboard, mouse, and monitor_ +- Raspberry Pi 3B+ (or better). +- 16 GB micro SD card (or bigger). +- Power supply for the RPi. + +At least **one of** the following: + +- An ethernet connection (plugged in to the RPi). +- A keyboard, monitor, and mouse. + +_**Note**: you will be able to configure WiFi later in the setup. If neither of the above two options are available to you, you will need to [use a wpa_supplicant.conf](https://www.raspberrypi.org/documentation/configuration/wireless/headless.md) to pre-configure WiFi._ + +Additionally, the first time Makerverse starts, you will need an active internet connection. ## Choose Release @@ -28,30 +36,42 @@ There are two download options in the [Latest Release](https://github.com/makerm These are merely customized versions of [the official Raspberry Pi OS images of the same names](https://www.raspberrypi.org/downloads/raspberry-pi-os/) (Lite vs. Desktop). Once you have downloaded the appropriate release file, unzip it and flash the `.img` to your SD card with your preferred application (e.g., Balena Etcher). -## First Boot +Then, just plug the RPi in and power it up! + +## Connecting to the RPi You'll need to get to a terminal in order to setup the Pi. You can either: - Attach a mouse and keyboard. -- Use SSH to connect from your computer: `ssh pi@makerverse.local` (SSH is enabled by default in the Pi image). +- Use SSH to connect from your computer: `ssh pi@makerverse.local`. -_**Note**: if the SSH command does not work, either the Pi is not connected to your home network via ethernet, or your router does not support looking up the Pi by its name. In either case, you should open your router's admin interface and try to find the Pi's IP address on the network. If you can find the IP address, you can use it instead of `makerverse.local`._ +_**Note**: SSH is enabled by default in the Pi image. If the SSH command cannot connect (does not show a login prompt), either the Pi is not connected to the same network as the computer from which you are attempting to access it, or your router does not support looking up the Pi by its name. In either case, you should open your router's admin interface and try to find the Pi's IP address on the network. If you can find the IP address, you can use it instead of `makerverse.local`._ The username/password (`pi`/`raspberry`) have been left unchanged from a "normal" Raspberry Pi OS. Use this whenever prompted for a username and password. +## First Boot + Once you've got a terminal open, type `sudo raspi-config` to run the official Raspberry Pi configuration tool. - You should **definitely** change the password, to keep the device secure! - You might also change the hostname from `makerverse` to something more memorable, like `maslow`, so you can use `maslow.local` instead of `makerverse.local`. - You might also want to turn on WiFi, so you do not need to use an ethernet connection on the Raspberry Pi to have access to Makerverse. -The Makerverse application will start automatically on port `8000`. However, especially during the first boot, it will take some time to download (_~600MB_) and unpack the application. On a Raspberry Pi 3 B+ Rev.1.3 (about the worst device which can handle Makerverse), this has been known to take 20-30 minutes. A RPi4 on a decent internet connection should only take a few minutes. - _**Tip**: read the [useful commands in the Linux Service section](/installation/web-server/linux-service/#useful-commands)!_ +_**Note**: GPIO pin communication is enabled by default in Makerverse (meaning that `pigpiod` is enabled). This allows you to [create commands](/features/commands/) that turn on and off the machine, for example._ + +## Opening Makerverse + +You can connect to Makerverse from any web browser on the same network. + +_**Note**: the Raspberry Pi image, unlike other web server instals, will run the Makerverse server on port `80` instead of port `8000`. This means that you can connect without specifying a port in your browser (e.g., `http://makerverse.local` instead of `http://makerverse.local:8000`)._ + +The Makerverse application will start automatically on port `80`. However, especially during the first boot, it will take some time to download (_~600MB_) and unpack the application. On a Raspberry Pi 3 B+ Rev.1.3 (about the worst device which can handle Makerverse), this has been known to take 20-30 minutes. A RPi4 on a decent internet connection should only take a few minutes. To check on the status of the startup or update, see the [useful commands in the Linux Service section](/installation/web-server/linux-service/#useful-commands). + ## Tablet UI -The Raspberry Pi image comes pre-installed with a mobile/tablet UI. It can be accessed by adding `/tablet` to the URL, such as `http://makerverse.local:8000/tablet`. +The Raspberry Pi image comes pre-installed with a mobile/tablet UI. It can be accessed by adding `/tablet` to the URL, such as `http://makerverse.local/tablet`. However, this UI is not the default UI because it is much less full-featured (it is intended for simple controls, like jogging or pausing program execution, from the shopfloor). You will still need to perform setup and calibration using the normal, desktop UI. @@ -59,7 +79,7 @@ However, this UI is not the default UI because it is much less full-featured (it When running the `makerverse-raspberrypi-os-dekstop.**` (desktop version), you will need to follow on-screen instructions after the first boot to configure your Raspberry Pi. This image is based upon a standard Raspberry Pi OS Desktop installation, so please refer to the official documentation for any help. -You can open a web browser and navigate to Makerverse at `http://localhost:8000`. Or, you can enable Kiosk mode... +You can open a web browser and navigate to Makerverse at `http://localhost`. Or, you can enable Kiosk mode... ### Kiosk Mode diff --git a/docs/machines/cnc/index.md b/docs/machines/cnc/index.md index 9b375d4dc..11775a607 100644 --- a/docs/machines/cnc/index.md +++ b/docs/machines/cnc/index.md @@ -8,21 +8,22 @@ has_children: true # CNC -Find your machine, below, and click on the appropriate link for the latest firmware. +Find your machine, below, and click on the appropriate link for the latest firmware and instructions. + +_If you click on one of the links and are taken to a Github page, use the green **Code** button at the top to download the latest version, (unless specified otherwise in the instructions)._ ## Maslow _Please read the [Maslow-specific instructions](/machines/cnc/maslow)._ -- [Arduino Mega](https://github.com/WebControlCNC/Firmware/tree/release/holey): Maslow "Classic" (JumpStart Kit) (Baud Rate: 57600) -- [Arduino Due](https://github.com/makermadecnc/MaslowDue): M2 (Baud Rate: 38400) +There are two common types of Maslow, built with two different Arduino boards: -#### Tested On +- [Arduino Mega](https://github.com/WebControlCNC/Firmware/tree/release/holey): Maslow "Classic" (JumpStart Kit) +- [Arduino Due](https://github.com/makermadecnc/MaslowDue): M2, or similar + +_**Tip**: Coming from GroundControl/WebControl with an original Maslow Mega? Read [this forum post](https://forums.maslowcnc.com/t/how-to-upgrade-to-holey-51-28-firmware-using-webcontrol-in-preparation-for-running-makerverse/14549) for help upgrading firmware._ -- MakerMade JumpStart Kit -- MakerMade M2 -- MetalMaslow Kit -- MetalMaslow Due + Shield +_**Note**: the firmware for the Arduino Due underwent significant changes in September, 2020. If your firmware was installed before this point, it is actually a Grbl machine (below) and does not have support for the [Maslow-specific features](/machines/cnc/maslow), like correcting for chain-sag effects (rounding) that happen in the corners of the stock._ ## Grbl diff --git a/docs/machines/cnc/maslow.md b/docs/machines/cnc/maslow.md index 00c3a1751..5ca0502a1 100644 --- a/docs/machines/cnc/maslow.md +++ b/docs/machines/cnc/maslow.md @@ -8,11 +8,9 @@ nav_order: 1 # Maslow -The Maslow is a unique CNC machine due to its hanging "pendant" design. +The Maslow is a unique CNC machine due to its "hanging pendant" design. -## Firmware - -Coming from GroundControl/WebControl? Read [this forum post](https://forums.maslowcnc.com/t/how-to-upgrade-to-holey-51-28-firmware-using-webcontrol-in-preparation-for-running-makerverse/14549) for help upgrading firmware. +First, [determine which version you have](/machines/cnc/) and install the latest firmware. ## Calibration @@ -26,7 +24,7 @@ Do a **pre-flight check**. Maslow frames are generally built from hand-cut, imprecise materials. Catching errors early will greatly improve the chances of an easy, successful calibration. -Use the Shuttle controls to move your sled to all 4 corners of the stock. Check that it can reach each corner easily and without obstruction. If you have any of these problems, do **not** attempt to calibrate: +Use the Shuttle controls to move your sled to all 4 corners of the stock. Check that it can reach each corner easily and without obstruction. Do **not** attempt to calibrate if you have any of these problems: - Bowing or warping of the stock. - Sled lifting or tilting while moving. @@ -47,7 +45,11 @@ These options may not need to be changed, as they default to match standard Masl ### Stock -During calibration, you should make sure that these values match the stock you have loaded. **Measure your stock!** Most plywood is exactly 8x4 feet, but it is important to be certain about these values before calibrating. +During calibration, you should make sure that these values match the stock you have loaded. + +**Measure your stock!** + +Most plywood is exactly 8x4 feet, but it is important to be certain about these values before calibrating. - **Width**: the width of the stock. - **Height**: the height of the stock. @@ -67,6 +69,8 @@ If these two values are not accurate within +/- 5mm, it is likely that the subse ### Sled +_If you used a pre-configured machine from the community catalog when setting up your workspace, this step should already be completed._ + This step measures the distance from the end-mill (tip of the router) to the four edges of the sled. If you have "standard" Maslow kit (with a circular sled 18" in diameter), it is likely that you do not need to change anything. @@ -75,6 +79,8 @@ The purpose of this step is to allow calibration to infer where the end-mill is ### Z-Axis +_If you used a pre-configured machine from the community catalog when setting up your workspace, this step should already be completed._ + This step will ensure that the Z-axis travels the correct distance, and invert the Z-axis (if needed). You will move the Z-axis by some amount (up or down), and then enter the actual distance moved. Calibration will simply scale the Z-axis based upon the actual distance moved. @@ -85,15 +91,17 @@ Alterantively, you can use the "Edit Raw Z-Axis Values" at the bottom of the scr This step will tell the machine where the end-mill is currently located. -It will also produce a "save point" to return to (_home_) in case the machine ever becomes un-calibrated (such as chains slipping or being removed from the sprockets). +It is a one-time process that will create a "save point" to return to (_home_) in case the machine ever becomes un-calibrated (such as chains slipping or being removed from the sprockets). This "save point" is really just a measurement of the length of both chains. Internally, the chain length is what the Maslow uses to compute the X/Y position. This step will help the Maslow find the correct chain length, and then save that length into its internal memory. -_**Tip**: As you complete the "Set Chains", use a sharpie or paint to mark exactly which link of the chain is at the top of each sprocket. If your machine ever comes out of alignment, such as if chains slip or are removed from the sprockets, you will need to return it to this position. It is important that the chains are exactly in the same position (within 1mm). **Do not try to visually move the sled back to the same position**. Most users simply mark the chain link which is at the 12 o'clock (noon) position on the sprocket. Once you are certain the chain is in the exact same position, press the "Reset Chains" button on the main screen and Makerverse will tell the Maslow it is back at this saved location._ +As you complete the "Set Chains" instructions in the app, you will use a sharpie or paint to mark exactly which link of the chain is at the top of each sprocket. If your machine ever comes out of alignment, such as if chains slip or are removed from the sprockets, you will need to return it to this position. It is important that the chains are exactly in the same position. **Do not try to visually move the sled back to the same position**. It is more accurate to use the 12 o'clock (noon) position on the sprocket matching up with your mark on the chain. Once you are certain the chain is in the exact same position, press the "Reset Chains" button on the main screen and Makerverse will tell the Maslow it is back at this saved location. There is **no need** to re-calibrate after resetting chains. ### Edge Calibration Edge calibration is a way to refine X/Y positioning without actually cutting (destroying) stock. -Both Edge and Precision calibration will use measurements to correct for chain sag and ensure that your sled is in the correct X/Y position. However, these steps may also modify your motor width and motor height to account for slight measurement errors. For the best results, use a millimeter tape measure to take measurements in these steps. +Both Edge and Precision calibration will use measurements to correct for chain sag and ensure that your sled is in the correct X/Y position. They can be performed again and again, if necessary, to incrementally improve calibration. + +_**Tip**: For the best results, use a millimeter tape measure to take measurements in these steps._ - First ensure that you have selected the correct sled type from the bottom of the screen. The default is a circular sled with a 9" radius. - Press each of the six **move** buttons to move the sled into that location. @@ -112,15 +120,6 @@ This is very similar to Edge Calibration, except that this time the Maslow will Using a 1/8" end-mill, it should be possible to easily achieve an **average error distance** of less that `2mm` and a **max error distance** of less than `4mm`. With several rounds of calibration, values of less than `1mm` and `2mm` should be entirely attainable. -### Z-Axis Calibration - -**Important**: different shields require different hardware settings. - -You should not need to change anything with the Mega, but there are some extra steps for the Arduino Due. You may need to change the following: - -- **MakerMade M2** (V2 shield): Make sure **Step pulse invert** (`$3`) is set to `4` (inverts the Z-axis). Also make sure **Z-axis travel resolution** (`$102`) is set to `472.5` (scales the Z-axis). -- **V1 Shield**: You may need to change **Z-axis travel resolution** (`$102`) based upon your gear tooth ratio. - ## Further Reading - [Getting Starting with the Maslow CNC Router](https://www.technicallywizardry.com/maslow-cnc-router-simplified-guide/) diff --git a/docs/machines/index.md b/docs/machines/index.md index 7e07b7e33..4b30d239d 100644 --- a/docs/machines/index.md +++ b/docs/machines/index.md @@ -1,6 +1,6 @@ --- layout: default -nav_order: 2 +nav_order: 3 title: Machines permalink: /machines/ has_children: true @@ -12,23 +12,15 @@ Makerverse uses various [controllers](/features/#controllers) to speak to differ ## Supported Machines -_**Note**: in order to make the controller setup process easier, we are working on compiling a list of well-tested machines in Makerverse (see: Table of Contents, below)._ - -From the homescreen, to create a new workspace for your machine, you need to select: - -- The correct USB port. -- The correct [controller](/features/#controllers). -- The correct **baud rate** for your firmware (_see Firmware, below_). +_**Note**: when [creating a workspace](/tutorial/create-workspace/), some machines come pre-configured via the community catalog._ If you _cannot find your machine_ (in the app or in this documentation), it is nevertheless _likely to still be supported_ (as long as it uses a standard protocol). You will need to identify the correct **controller** for the protocol, as well as the baud rate (which is probably buried somewhere in your machine's documentation). ## Firmware -Firmware is the code which runs on the machine itself (usually, an Arduino board connected via USB). - -Your machine likely came pre-installed with some firmware. Generally, you should be certain you are using the latest firmware for your machine. In the list of well-tested machines, you might find a link to the specific well-tested version of the firmware. When in doubt, it's best to use this specific version. +Firmware is the code which runs on the machine itself (usually, an Arduino board connected via USB). Your machine likely came pre-installed with some firmware. -The firmware also determines which **baud rate** to use. In the list below, the correct baud rates are noted. If your machine is not listed, please refer to the manufacturer documentation to determine the correct baud rate. +Generally, you should be certain you are using the latest firmware for your machine. If you have selected a machine from the community catalog, you will receive recommendations and support links for your firmware. ## Machine-Specific Instructions diff --git a/docs/tutorial/create-workspace.md b/docs/tutorial/create-workspace.md new file mode 100644 index 000000000..78c5dc5dd --- /dev/null +++ b/docs/tutorial/create-workspace.md @@ -0,0 +1,64 @@ +--- +layout: default +title: Create Workspace +parent: Tutorial +nav_order: 2 +--- + +# Creating a Workspace + +With [Makerverse open](/tutorial/connect), you can now create a Workspace. + +## What's in a Workspace? + +A **workspace** holds a connection to a single machine (CNC, 3D printer, etc.) + +It knows how to "talk to" the machine (what port the machine uses, for example). It will run your prints/cuts and generally be the home of your machine. + +A workspace **does not** store machine settings. In almost every case, your machine itself stores things like the calibration settings. This means that you can detach the machine from the USB port and safely connect it to a different computer (running Makerverse, or any other program compatible with your machine) and the machine will continue to function. + +## New Workspace + +Find the **New Workspace** window on the **Home** (first tab) of makerverse. + +### Pre-Configured Machines + +OpenWorkShop maintains a "community catalog" of pre-configured machines. + +When you choose from the catalog, Makerverse will automatically choose the correct options for you. Pre-configured machines will also check that you are running the correct firmware version. + +Just choose the name of your machine from the "New Workspace" screen. + +### Create New Machine + +If you **cannot find** your machine in the community catalog, you will need to use the "Create New Machine" button. On this screen, you will need to enter the controller type (e.g., Grbl, Marlin), baud rate, and eventually the size of each axis. + +### Connect + +Once you've configured the machine, the **Connect** button will appear. + +You will need to choose the correct port to which the machine is connected. If you see a simple **error opening serial port** when you try to connect, either you do not have permission to open the port, or it is otherwise busy. + +## Customize Workspace + +You can choose the name, background color, icon, and other traits of your workspace. + +### Axes + +If you used a pre-configured machine, your axes are already set. + +In other cases, you should take the time to make sure your axes are correctly set. + +_**Note**: axes settings have no impact upon the actual functioning of the machine. They merely change the UI to be more conveniently sized._ + +The `accuracy` value specifies the minimum distance the machine can move along that axis. For example, `0.1`mm might be appropriate to a CNC machine, but not to a 3D printer. + +The `precision` value indicates the number of digits used for rounding the (displayed) value of the axis. For example, `0` would round the value to the whole `mm`. + +## New Machine? + +Some machines, like the [Maslow](/machines/cnc/maslow), may ask if this is a new machine (or the firmware has been recently re-installed). If you select "Yes," the machine settings will be reset and the recommended settings will be applied. You may then be asked to calibrate the machine before moving on... + +## Next Steps + +Learn how to control your machine manually in the [workspace basics](/tutorial/workspace-basics). diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md new file mode 100644 index 000000000..6305acc3f --- /dev/null +++ b/docs/tutorial/index.md @@ -0,0 +1,9 @@ +--- +layout: default +nav_order: 2 +title: Tutorial +permalink: /tutorial/ +has_children: true +--- + +# Tutorial diff --git a/docs/tutorial/open-makerverse.md b/docs/tutorial/open-makerverse.md new file mode 100644 index 000000000..09f42ddcb --- /dev/null +++ b/docs/tutorial/open-makerverse.md @@ -0,0 +1,44 @@ +--- +layout: default +title: Open Makerverse +parent: Tutorial +nav_order: 1 +--- + +# Open Makerverse + +If you used a [Stand-Alone installation](/installation/stand-alone/), Makerverse should already be open and running. + +# Web Browser + +To connect to Makerverse from **any internet browser** on the same network, you first need to know the **address** and **port** of Makerverse. + +_**Tip**: with the Raspberry Pi image, the address is `makerverse.local` and the default port is `80`. On all other installations, the default port is `8000`._ + +The **address** of Makerverse can be the IP address of the computer on the network, or the name of that computer. Here's [how to find your hostname](https://computing.cs.cmu.edu/help-support/find-hostname) or IP address. Now, put the two together into your internet browser: + +``` +http://[hostname-or-ip]:[port]/ +``` + +_**Tip**: if you use port 80, you don't need to include the port_. + +## Examples + +### Raspberry Pi installation + +`makerverse.local` + port `80`: [http://makerverse.local/](http://makerverse.local/) + +### Using a Hostname + +`mycomputer.local` + port `8000`: [http://mycomputer.local:8000/](http://mycomputer.local:8000/) + +### Using an IP address + +IP `192.168.0.100` + port `8000`: [http://192.168.0.100:8000/](http://192.168.0.100:8000/) + +# Troubleshooting + +If your browser fails to connect to Makerverse, first make sure you have typed `http://` correctly (sometimes `https://` is inserted automatically). + +Next, check that you can access Makerverse on the same computer which is running Makerverse. Instead of the IP address or hostname, just use `localhost`. For example, try to open a web browser on the same computer to `http://localhost:8000`. If that works, then something about your network (e.g., firewall) is preventing the second computer from talking to the Makerverse computer. If it does not work, then Makerverse is not actually running. diff --git a/docs/tutorial/run-programs.md b/docs/tutorial/run-programs.md new file mode 100644 index 000000000..ec46112f8 --- /dev/null +++ b/docs/tutorial/run-programs.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Run Programs +parent: Tutorial +nav_order: 4 +--- + +# Run Programs + +A "program" is a set of instructions which tells your machine what to print, cut, etc. + +## Supported Programs + +Makerverse supports `gcode` (`.nc` files). + +_**Note**: this page assumes you already know how to create a program for your machine. [Easel](https://easel.inventables.com/) is popular for creating simple programs, while Fusion360 and other CAD programs are more feature-rich. Please refer to your machine's documentation, owner's group, or forums for more help._ + +## Upload Programs + +From your workspace, press the "Upload Program" button to select a file on the current computer. + +When using a web-server installation, you can also use the arrow on the right side of the button to browse the "Watch Directory." This directory is located at `$HOME/gcode` on the computer running Makerverse. Any files placed directly in the folder (not in sub-folders) will be visible to Makerverse. + +Once the program has been selected, it will appear in the **visualizer** at the center of the screen. + +## Align Work Position + +The **Work Position** defines where the program begins. + +Therefore, you may wish to change the work position to align the program in the visualizer with your desired location. However, note that each program also has an origin. For example, in Easel, the origin is the bottom-left of your design. In Fusion 360, the origin might be set to the center of the design. When you change the work position, you are setting the location for the origin of the program. + +## Start the Program + +The "play" button to the right of the Upload button will start the program. + +Some programs may indicate feedback, or require user input via banners at the bottom of the screen. For example, a `M6 (Tool Change)` will pause the program and wait for you to press the Play button in order to resume. + +Once the program begins, you can use the pause button to stop execution. + +_**Tip**: pausing execution stops sending commands. The current command will still finish. In case of emergency, use the red Reset/Halt button._ + +### Paused Programs + +While paused, movement controls will remain deactivated. This prevents losing your position during the job. To regain control, you will need to use the **stop** button, to the right of the pause button. + +### Stopped Programs + +Once stopped, a program must be restarted from the beginning with the **play** button. + +You can also unload the program by using the red trash icon (which replaces the stop button). + +## Completion + +You can use the **G-code widget** on the right side to watch the progress of the program, including an (estimated) remaining time. + +When the program completes, execution will simply stop. diff --git a/docs/tutorial/workspace-basics.md b/docs/tutorial/workspace-basics.md new file mode 100644 index 000000000..b31822a07 --- /dev/null +++ b/docs/tutorial/workspace-basics.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Workspace Basics +parent: Tutorial +nav_order: 3 +--- + +# Workspace Basics + +First, **open** the **connection** to your machine (via the top-left widget). + +## Console + +Below the connection widget is the **console**. + +This shows the direct output from the machine as it runs. You can also use it to issue commands directly to the machine. + +_**Tip**: watch the console! You can learn a lot from observing the commands issued to your machine._ + +## Machine + +Below the console, you will find your machine-specific settings, configurations, calibration, etc. (which will vary based upon the type of machine you have connected). + +## Visualizer + +The center of the screen shows the **visualizer**. + +At the top, it will inform you of errors or alerts. In the main area, it will show any loaded programs. You can zoom, pan, and tilt in all three dimensions to observe your machine. + +## Controls + +In the upper-right, you can find the **controls** widget. + +Use the **yellow & blue arrow buttons** to manually move the machine. + +_**Tip**: if the movement buttons are grayed out, your machine may need to be unlocked._ + +As the machine moves, observe: + +* **Machine Position**: the absolute, "real" location of the machine. +* **Work Position**: the relative location, used when [running a program](/tutorial/run-programs). + +_**Tip**: if your machine position is wrong, it may need to be calibrated or homed._ + +Use the "pin" icons underneath any of the values to set the current position as zero. + +## Other Widgets + +- **G-code**: shows the status of any currently uploaded program. +- **Probe**: runs a "probe" command to zero an axis (if your machine supports it). +- **Spindle**: controls cutter speed, coolant, etc. (if your machine supports it). +- **Laser**: controls laser power, etc. (if your machine supports it). +- **Webcam**: connects to a camera attached to the Makerverse computer for monitoring. + +## Next Steps + +See: [running a program](/tutorial/run-programs). diff --git a/src/app/containers/Home/CreateWorkspace/ChooseMachine.jsx b/src/app/containers/Home/CreateWorkspace/ChooseMachine.jsx index 62edb5118..7aad7dcc2 100644 --- a/src/app/containers/Home/CreateWorkspace/ChooseMachine.jsx +++ b/src/app/containers/Home/CreateWorkspace/ChooseMachine.jsx @@ -299,9 +299,9 @@ class ChooseMachine extends React.PureComponent { {!machineProfiles &&
Loading...
} {!hasData && (
- {i18n._('Could not download machine profiles.')} + {i18n._('Could not download from the community catalog.')}
- {i18n._('You will need to use "manual connection mode," below.')} + {i18n._('You will need to create a new machine, below.')}
)} {showMachineProfile && this.renderMachineProfile(machineProfile)} diff --git a/src/app/containers/Home/CreateWorkspace/ConnectedHardware.jsx b/src/app/containers/Home/CreateWorkspace/ConnectedHardware.jsx index 93fb1c321..fba5e5e06 100644 --- a/src/app/containers/Home/CreateWorkspace/ConnectedHardware.jsx +++ b/src/app/containers/Home/CreateWorkspace/ConnectedHardware.jsx @@ -113,7 +113,7 @@ class ConnectedHardware extends React.PureComponent { componentDidMount() { setTimeout(() => { this.setState({ timeoutElapsed: true }); - }, 5000); + }, 10000); } render() { diff --git a/src/app/containers/Home/CreateWorkspace/CreateWorkspacePanel.jsx b/src/app/containers/Home/CreateWorkspace/CreateWorkspacePanel.jsx index cec24f8ef..251d9bfb3 100644 --- a/src/app/containers/Home/CreateWorkspace/CreateWorkspacePanel.jsx +++ b/src/app/containers/Home/CreateWorkspace/CreateWorkspacePanel.jsx @@ -151,10 +151,10 @@ class CreateWorkspacePanel extends PureComponent { const canUseConnection = controllerType && baudRate && hasMachine; const canSwitchMachineMode = !canUseConnection; - const sw1 = isCustomMachine ? 'Not sure what settings to use?' - : 'Can\'t find your machine?'; - const sw2 = isCustomMachine ? 'Search for pre-configured machines' - : 'Switch to manual connection mode'; + const sw1 = isCustomMachine ? i18n._('Not sure what settings to use?') + : i18n._('Can\'t find your machine?'); + const sw2 = isCustomMachine ? i18n._('Search the Community Catalog') + : i18n._('Create a New Machine'); if (!fetchBegan) { return ( @@ -213,6 +213,7 @@ class CreateWorkspacePanel extends PureComponent { {sw2}
+
Makerverse can support almost any machine ( - {i18n._('Accuracy is unusual')} + {i18n._('Accuracy is unusual (defines minimum travel distance on axis).')} )} {!axis.validPrecision && ( - {i18n._('Precision is unusual.')} + {i18n._('Precision is unusual (defines number of digits for rounding).')} )} diff --git a/src/app/containers/Home/CreateWorkspace/FirmwareRequirement.jsx b/src/app/containers/Home/CreateWorkspace/FirmwareRequirement.jsx index 894717c4d..f1b6c30ca 100644 --- a/src/app/containers/Home/CreateWorkspace/FirmwareRequirement.jsx +++ b/src/app/containers/Home/CreateWorkspace/FirmwareRequirement.jsx @@ -65,8 +65,9 @@ class FirmwareRequirement extends React.PureComponent { const isOk = severity !== 'warning' && severity !== 'error'; const showHelp = !compatibility || !isOk; const hasProblem = compatibility && !isOk; + const showDownload = hasProblem || !compatibility; const latestVersion = firmware.suggestedVersion || firmware.requiredVersion; - const downloadText = hasProblem ? compatibility[severity] : + const dlText = hasProblem ? compatibility[severity] : i18n._('Download v{{ version }}', { version: latestVersion }); return ( @@ -74,7 +75,7 @@ class FirmwareRequirement extends React.PureComponent {
{i18n._('Firmware: {{ name }}', { name: firmware.name })}
- {this.renderDownloadText(firmware, downloadText)} + {showDownload && this.renderDownloadText(firmware, dlText)}
{showHelp && this.renderHelpLink(firmware)} diff --git a/src/app/lib/Maslow/MaslowCalibration.jsx b/src/app/lib/Maslow/MaslowCalibration.jsx index d8ad79c7f..ffcb1b7a8 100644 --- a/src/app/lib/Maslow/MaslowCalibration.jsx +++ b/src/app/lib/Maslow/MaslowCalibration.jsx @@ -64,13 +64,14 @@ class MaslowCalibration { // Custom sled. selectedSled.id = ''; selectedSled.data = customSledDimensions; - return; + return selectedSled; } try { selectedSled.data = JSON.parse(sleds[sledId].dataBlob); } catch (e) { log.error(e, 'sled selection'); } + return selectedSled; } static setCustomSledDimension(edge, value) { @@ -121,13 +122,14 @@ class MaslowCalibration { }; const origErr = this.calculateError(measured, this.idealCoordinates); const orig = { ...origSettings, ...origErr }; + log.debug('calibration begin', origSettings, origErr, orig); let op = { ...orig }; // Start by offsetting the motor offset by the y error, so it's a reasonable guess. - op.motorOffsetY -= Math.round(yError); + op.motorOffsetY -= yError ? Math.round(yError) : 0; const decimals = 4; for (let i = 0; i < decimals; i++) { - log.debug('calibration #', i); + log.debug('calibration #', i, op); op = this.optimize(measured, op, i, decimals, callback); } @@ -152,6 +154,7 @@ class MaslowCalibration { this.idealCoordinates = [homePoint, { x: 0, y: 0 }]; this.idealChainLengths = this.calculateChainLengths(this.idealCoordinates); this.opts.chainBounds = 0; + log.debug('Calibrate origin', this.opts, this.kin.opts); const ret = this._calibrate(measured); this.opts.chainBounds = chainBounds; this.recomputeIdeals(); @@ -244,9 +247,6 @@ class MaslowCalibration { start.motorOffsetY + mh, start.distBetweenMotors + mw ); - if (!opt) { - log.warn('Failed to compute location', left, right, mw); - } if (opt.maxErrDist < best.maxErrDist && opt.totalErrDist <= best.totalErrDist) { log.debug('new best', opt, 'change=', this.calculateChange(best, opt)); best = opt; @@ -285,6 +285,8 @@ class MaslowCalibration { const p = this.kin.chainToPosition(cl[0], cl[1], measured[x].x, measured[x].y); if (!p) { // Position would not be within bounds. Ignore the possibility. + log.warn('Failed to compute location', measured, leftChainTolerance, + rightChainTolerance, motorOffsetY, distBetweenMotors, this.idealChainLengths); return false; } points.push(p); diff --git a/src/app/lib/cookies.js b/src/app/lib/cookies.js index 5266bc24d..4a201b8f0 100644 --- a/src/app/lib/cookies.js +++ b/src/app/lib/cookies.js @@ -3,8 +3,8 @@ export function setCookie(name, val) { const date = new Date(); const value = val; - // Set it expire in 30 days - date.setTime(date.getTime() + 30 * 24 * 60 * 60 * 1000); + // Set it expire in 7 days + date.setTime(date.getTime() + 7 * 24 * 60 * 60 * 1000); console.log('set cookie', name, value); // Set it diff --git a/src/app/widgets/Maslow/CalibrationModal.jsx b/src/app/widgets/Maslow/CalibrationModal.jsx index f47bccb89..dd9b4b1b7 100644 --- a/src/app/widgets/Maslow/CalibrationModal.jsx +++ b/src/app/widgets/Maslow/CalibrationModal.jsx @@ -90,7 +90,7 @@ class CalibrationModal extends PureComponent { state = { ...this.internalState, measurements: defaultMeasurements, - activeTab: this.props.activeTab || 'machine', + activeTab: this.props.activeTab || 'welcome', setMachineSettings: false, setWorkspaceSettings: false, setFrameSettings: false, @@ -128,14 +128,22 @@ class CalibrationModal extends PureComponent { } } + setSledId(sledId) { + // setSled may fail... + const sled = MaslowCalibration.setSledId(sledId); + this.setState({ + sledId: sled.id, + sledDimensions: sled.data, + }); + } + componentDidMount() { this.workspace.addControllerEvents(this.controllerEvents); this.updateActiveTab(); const sled = this.workspace.findPart('SLED'); if (sled) { - MaslowCalibration.setSledId(sled.id); - this.setState({ sledId: sled.id }); + this.setSledId(sled.id); } } @@ -240,7 +248,6 @@ class CalibrationModal extends PureComponent { const pt = { x: this.toMM(xOff), y: this.toMM(yOff) }; const hp = { x: 0, y: this.state.yHome }; const res = this.calibration.calibrateOrigin(hp, pt); - log.debug('Center offset calibration', res); this.writeCalibrationResult(res); this.setState({ ...this.state, measuredChains: res }); } @@ -537,7 +544,7 @@ class CalibrationModal extends PureComponent { const zAxisDistancePerRotation = this.workspace.machineSettings.map.zAxisDistancePerRotation; const zAxisResSetting = this.workspace.machineSettings.map.zAxisRes; - const canShowTabs = curTab !== 'triangular'; + const canShowTabs = curTab !== 'welcome'; return ( )}
+ {curTab === 'welcome' && ( +
+
{i18n._('Welcome')}
+ If you have not tested your frame before, please run a pre-flight check. +
+ For help with this (or any other step), see the Calibration Help at the bottom. +
+
+ +
+ )} {curTab === 'triangular' && (
@@ -921,15 +946,7 @@ class CalibrationModal extends PureComponent { - {' Y Offset: '} + {' Y Error: '}
- {this.renderToolbar(this.renderPrevPage(), this.renderFinish())} + {this.renderToolbar(this.renderPrevPage(), this.state.movedToCenter && this.renderFinish())}
); }