diff --git a/docs/byop/motherboard/mounting/index.md b/docs/byop/motherboard/mounting/index.md index 3abfddfac..916b50c71 100644 --- a/docs/byop/motherboard/mounting/index.md +++ b/docs/byop/motherboard/mounting/index.md @@ -58,4 +58,4 @@ Now that we've got all the THT components soldered in, it's time to mount the mo ## Next steps -Make sure your motherboard is [running the latest firmware](../update-firmware/index.md). +Continue to [wiring and pneumatics](../../wiring-and-pneumatics/wiring-y-motors/index.md). diff --git a/docs/byop/motherboard/update-firmware/images/IMG_0749.JPG b/docs/guides/update-firmware/images/IMG_0749.JPG similarity index 100% rename from docs/byop/motherboard/update-firmware/images/IMG_0749.JPG rename to docs/guides/update-firmware/images/IMG_0749.JPG diff --git a/docs/byop/motherboard/update-firmware/images/PIO_upload_done.png b/docs/guides/update-firmware/images/PIO_upload_done.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/PIO_upload_done.png rename to docs/guides/update-firmware/images/PIO_upload_done.png diff --git a/docs/byop/motherboard/update-firmware/images/STM32_COM_port_connected.png b/docs/guides/update-firmware/images/STM32_COM_port_connected.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/STM32_COM_port_connected.png rename to docs/guides/update-firmware/images/STM32_COM_port_connected.png diff --git a/docs/byop/motherboard/update-firmware/images/Screen Shot 2022-02-04 at 7.27.25 PM.png b/docs/guides/update-firmware/images/Screen Shot 2022-02-04 at 7.27.25 PM.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/Screen Shot 2022-02-04 at 7.27.25 PM.png rename to docs/guides/update-firmware/images/Screen Shot 2022-02-04 at 7.27.25 PM.png diff --git a/docs/byop/motherboard/update-firmware/images/browse-for-binary.png b/docs/guides/update-firmware/images/browse-for-binary.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/browse-for-binary.png rename to docs/guides/update-firmware/images/browse-for-binary.png diff --git a/docs/byop/motherboard/update-firmware/images/connect-to-motherboard.png b/docs/guides/update-firmware/images/connect-to-motherboard.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/connect-to-motherboard.png rename to docs/guides/update-firmware/images/connect-to-motherboard.png diff --git a/docs/byop/motherboard/update-firmware/images/connect_STM_to_programmer.png b/docs/guides/update-firmware/images/connect_STM_to_programmer.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/connect_STM_to_programmer.png rename to docs/guides/update-firmware/images/connect_STM_to_programmer.png diff --git a/docs/byop/motherboard/update-firmware/images/dfu_mode_device_manager.png b/docs/guides/update-firmware/images/dfu_mode_device_manager.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/dfu_mode_device_manager.png rename to docs/guides/update-firmware/images/dfu_mode_device_manager.png diff --git a/docs/byop/motherboard/update-firmware/images/download-tab.png b/docs/guides/update-firmware/images/download-tab.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/download-tab.png rename to docs/guides/update-firmware/images/download-tab.png diff --git a/docs/byop/motherboard/update-firmware/images/firmware_download_done.png b/docs/guides/update-firmware/images/firmware_download_done.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/firmware_download_done.png rename to docs/guides/update-firmware/images/firmware_download_done.png diff --git a/docs/byop/motherboard/update-firmware/images/linux_lsusb.png b/docs/guides/update-firmware/images/linux_lsusb.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/linux_lsusb.png rename to docs/guides/update-firmware/images/linux_lsusb.png diff --git a/docs/byop/motherboard/update-firmware/images/linux_lsusb_bootloader.png b/docs/guides/update-firmware/images/linux_lsusb_bootloader.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/linux_lsusb_bootloader.png rename to docs/guides/update-firmware/images/linux_lsusb_bootloader.png diff --git a/docs/byop/motherboard/update-firmware/images/marlin-auto-build-ui.png b/docs/guides/update-firmware/images/marlin-auto-build-ui.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/marlin-auto-build-ui.png rename to docs/guides/update-firmware/images/marlin-auto-build-ui.png diff --git a/docs/byop/motherboard/update-firmware/images/open_firmware_bin_file.png b/docs/guides/update-firmware/images/open_firmware_bin_file.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/open_firmware_bin_file.png rename to docs/guides/update-firmware/images/open_firmware_bin_file.png diff --git a/docs/byop/motherboard/update-firmware/images/rect34.png b/docs/guides/update-firmware/images/rect34.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/rect34.png rename to docs/guides/update-firmware/images/rect34.png diff --git a/docs/byop/motherboard/update-firmware/images/refresh-button.png b/docs/guides/update-firmware/images/refresh-button.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/refresh-button.png rename to docs/guides/update-firmware/images/refresh-button.png diff --git a/docs/byop/motherboard/update-firmware/images/select-port.png b/docs/guides/update-firmware/images/select-port.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/select-port.png rename to docs/guides/update-firmware/images/select-port.png diff --git a/docs/byop/motherboard/update-firmware/images/start-programming.png b/docs/guides/update-firmware/images/start-programming.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/start-programming.png rename to docs/guides/update-firmware/images/start-programming.png diff --git a/docs/byop/motherboard/update-firmware/images/start_firmware_download.png b/docs/guides/update-firmware/images/start_firmware_download.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/start_firmware_download.png rename to docs/guides/update-firmware/images/start_firmware_download.png diff --git a/docs/byop/motherboard/update-firmware/images/upload-done.png b/docs/guides/update-firmware/images/upload-done.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/upload-done.png rename to docs/guides/update-firmware/images/upload-done.png diff --git a/docs/byop/motherboard/update-firmware/images/usb-connection.png b/docs/guides/update-firmware/images/usb-connection.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/usb-connection.png rename to docs/guides/update-firmware/images/usb-connection.png diff --git a/docs/byop/motherboard/update-firmware/images/vscode-dfu-util-integrated-terminal.png b/docs/guides/update-firmware/images/vscode-dfu-util-integrated-terminal.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/vscode-dfu-util-integrated-terminal.png rename to docs/guides/update-firmware/images/vscode-dfu-util-integrated-terminal.png diff --git a/docs/byop/motherboard/update-firmware/images/vscode_marlin_env.png b/docs/guides/update-firmware/images/vscode_marlin_env.png similarity index 100% rename from docs/byop/motherboard/update-firmware/images/vscode_marlin_env.png rename to docs/guides/update-firmware/images/vscode_marlin_env.png diff --git a/docs/byop/motherboard/update-firmware/index.md b/docs/guides/update-firmware/index.md similarity index 83% rename from docs/byop/motherboard/update-firmware/index.md rename to docs/guides/update-firmware/index.md index 6742b7ce7..4ba903515 100644 --- a/docs/byop/motherboard/update-firmware/index.md +++ b/docs/guides/update-firmware/index.md @@ -1,19 +1,20 @@ -# Update the Firmware +# Update LumenPnP Firmware -All motherboards come pre-flashed with firmware from Opulo and should work out of the box without these steps. If you're setting up a LumenPnP with feeders for the first time, you may need to update your LumenPnP's firmware. - -!!! danger "Important" - It is important that you pick the correct firmware file for your machine. - - - If you have a v2, choose `v2-lumenpnp-firmware-feeder-support.bin`. - - If you have a v3, choose `v3-lumenpnp-firmware-feeder-support.bin`. +All motherboards come pre-flashed with firmware from Opulo and should work out of the box without these steps. If you need to update your LumenPnP's firmware, this guide will help you do so. ## Option 1: Prebuilt Firmware and STMProgrammer (RECOMMENDED) The easiest way to update your LumenPnP's motherboard is to use a precompiled binary of the firmware, and the [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html) software by ST. 1. Download the latest [precompiled firmware](https://github.com/opulo-inc/lumenpnp/releases) `.bin` file for your motherboard version. + + !!! danger "Important" + It is important that you pick the correct firmware file for your machine. + + - If you have a v2, choose `v2-lumenpnp-firmware-feeder-support.bin`. + - If you have a v3, choose `v3-lumenpnp-firmware-feeder-support.bin`. + 2. Download and install [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html). 3. Open STM32CubeProgrammer. 4. Select `USB` from the connection type dropdown on the right. @@ -32,33 +33,33 @@ The easiest way to update your LumenPnP's motherboard is to use a precompiled bi !!! info "NOTE" If you have a hard time getting your board to enter DFU mode, instead try powering off the machine entirely, holding the 'BOOT' button, plugging in power, waiting 10 seconds, then release the `BOOT` button. -8. Click the refresh button in the `Port` line to detect the motherboard's port. +1. Click the refresh button in the `Port` line to detect the motherboard's port. ![Refresh button](images/refresh-button.png) -9. Select the newly discovered USB port from the `Port` dropdown menu. +2. Select the newly discovered USB port from the `Port` dropdown menu. ![Select USB Port](images/select-port.png) -10. Double-check the other fields on the right match the image above: +3. Double-check the other fields on the right match the image above: 1. `PID: 0xdf11` 2. `VID: 0x0483` 3. `Read Unprotect (MCU): Unchecked` 4. `TZEN Regression (MCU): Unchecked` -11. Click the green `Connect` button to connect to the motherboard. +4. Click the green `Connect` button to connect to the motherboard. ![Connect to Motherboard button](images/connect-to-motherboard.png) -12. Click the `Browse` button to browse for the binary you downloaded earlier. +5. Click the `Browse` button to browse for the binary you downloaded earlier. ![Click the browse button](images/browse-for-binary.png) -13. Click the `Start Programming` button to upload the firmware to the motherboard. +6. Click the `Start Programming` button to upload the firmware to the motherboard. ![Start Programming the motherboard](images/start-programming.png) -14. Let the upload finish. +7. Let the upload finish. ![Upload finished](images/upload-done.png) -15. Press the `reset` button on the motherboard to reboot it. +8. Press the `reset` button on the motherboard to reboot it. -16. The machine should show up as a COM/Serial Port on your PC now, and you should be able to access it via OpenPNP. If it doesn't, press the Reset button on the board again, or power-cycle the machine *after the flashing is completed*. +9. The machine should show up as a COM/Serial Port on your PC now, and you should be able to access it via OpenPNP. If it doesn't, press the Reset button on the board again, or power-cycle the machine *after the flashing is completed*. This is how you can check whether your machine is connected properly: @@ -67,10 +68,10 @@ This is how you can check whether your machine is connected properly: ## Option 2: Auto Build Marlin and `dfu-util` -!!! info "Marlin" - Building an older version of Marlin with the recommended config files won't work. If you are unsure whether a previously-downloaded local version of Marlin is the newest one, re-downloading it is the safest choice. +!!! info "Marlin Version" + LumenPnP feeders require some custom Marlin features that we have not yet merged into mainline. Before this happens, be sure you're pulling from our fork with these features. -1. Download the [latest Marlin firmware][marlin] and unzip it. +1. Download the [latest Marlin firmware with feeder support][marlin] and unzip it. 2. Install [VSCode][vscode] and its [PlatformIO extension][pIO]. 3. Open Marlin firmware's folder in VSCode. 4. Download the Marlin configuration files [here][marlin-config] and @@ -80,7 +81,7 @@ This is how you can check whether your machine is connected properly: 8. Try to build Marlin using the build button with the hammer icon as shown below. See [Troubleshooting](#troubleshooting-building-with-auto-build-marlin) for more help ![Marlin Auto Build screenshot](images/marlin-auto-build-ui.png) -9. Attach the LumenPnP Motherboard to your computer with the included USB cable (USB C to A for Motherboard 3.0, or USB B to A for Motherboard 4.0). +9. Attach the LumenPnP Motherboard to your computer with the included USB cable (USB C to A for Motherboard 3.0, or USB B to A for Motherboard 4.0). 10. Boot your motherboard into DFU Mode 1. Press and hold the `BOOT` button @@ -92,7 +93,7 @@ This is how you can check whether your machine is connected properly: !!! info "NOTE" If you have a hard time getting your board to enter DFU mode, instead try powering off the machine entirely, holding the 'BOOT' button, plugging in power, waiting 10 seconds, then release the `BOOT` button. -11. In the integrated terminal in the root of the repository, flash the Motherboard using `dfu-util` by running the command: +1. In the integrated terminal in the root of the repository, flash the Motherboard using `dfu-util` by running the command: ```shell dfu-util -d 0x0483:0xdf11 -s 0x08000000:leave -a 0 -D ./.pio/build/Opulo_Lumen_REV3/firmware.bin @@ -107,9 +108,9 @@ This is how you can check whether your machine is connected properly: * `-a 0` makes the tool use the alt setting required for flashing the ESP32. * `-D ./.pio/build/Opulo_Lumen_REV3/firmware.bin` is the path to the to-be-flashed firmware. If you want to flash another file, change this. -12. Wait for the process to finish. +2. Wait for the process to finish. -13. The machine should show up as a COM/Serial Port on your PC now, and you should be able to access it via OpenPNP. If it doesn't, press the Reset button on the board, or power-cycle the machine *after the flashing is completed*. +3. The machine should show up as a COM/Serial Port on your PC now, and you should be able to access it via OpenPNP. If it doesn't, press the Reset button on the board, or power-cycle the machine *after the flashing is completed*. This is how you can check whether your machine is connected properly: @@ -120,7 +121,7 @@ This is how you can check whether your machine is connected properly: Note that flashing the firmware using the Auto Build Marlin Plugin might work, but seems error-prone for most people. We recommend using `dfu-util` as described above. Here are the steps to use Auto Build Marlin if you'd like to try it. -1. Download the [latest Marlin firmware][marlin] and unzip it. +1. Download the [latest Marlin firmware with feeder support][marlin] and unzip it. 2. Install [VSCode][vscode] and its [PlatformIO extension][pIO]. 3. Open Marlin firmware's folder in VSCode. 4. Download the Marlin configuration files [here][marlin-config]. @@ -183,13 +184,13 @@ This is how you can check whether your machine is connected properly: ## Flashing Factory Firmware -If you've put new firmware on your motherboard, but just want to get back to the firmware that your machine was flashed with, check the release for your build number and download the .bin firmware file attached to it. Put your board into DFU mode as described above, connect to your computer, and flash the binary to the board using the following command: +If you've put new firmware on your motherboard, but want to reinstall the firmware that your machine was flashed with, check the release for your build number and download the .bin firmware file attached to it. Put your board into DFU mode as described above, connect to your LumenPnP over USB, and flash the binary to the board using the STMProgrammer tool, or the following command (for Mac and Linux): ```shell -`dfu-util -d 0x0483:0xdf11 -s 0x08000000:leave -a 0 -D ~/path/to/firmware.bin` +dfu-util -d 0x0483:0xdf11 -s 0x08000000:leave -a 0 -D ~/path/to/firmware.bin ``` -Once flashing is completed, the machine should automatically exit DFU mode, and be accessible to OpenPNP again. +Once flashing is completed, press the reset button on the motherboard boot into the new firmware. ## Troubleshooting @@ -210,13 +211,11 @@ If you aren't able to upload, you can check to see if your motherboard is bootin Also, reference [the Marlin instructions for uploading](https://marlinfw.org/docs/basics/install_platformio.html). -## Next steps -Continue to [wiring and pneumatics](../../wiring-and-pneumatics/wiring-y-motors/index.md). [abmvs]: https://marketplace.visualstudio.com/items?itemName=MarlinFirmware.auto-build [marlin-docs]: https://marlinfw.org/docs/basics/auto_build_marlin.html [marlin-config]: https://github.com/MarlinFirmware/Configurations/tree/import-2.1.x/config/examples/Opulo/Lumen_REV4 -[marlin]: https://github.com/MarlinFirmware/Marlin/ +[marlin]: https://github.com/sphawes/Marlin/tree/feeder-safety [vscode]: https://code.visualstudio.com/ [pIO]: https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide diff --git a/docs/misc/photon/img/photon-packet.png b/docs/misc/photon/img/photon-packet.png new file mode 100644 index 000000000..b3b1a0ea9 Binary files /dev/null and b/docs/misc/photon/img/photon-packet.png differ diff --git a/docs/misc/photon/index.md b/docs/misc/photon/index.md new file mode 100644 index 000000000..2a107863f --- /dev/null +++ b/docs/misc/photon/index.md @@ -0,0 +1,174 @@ +# Photon Protocol + +The Photon Protocol is designed to facilitate ids and uuids + +Only the host may initiate communication. Every Photon interaction is comprised of two packets: one packet from the host with a command and optional payload, and a response from a feeder with a status and optional payload of information. + +broadcast and unicast + +The following is the basic Photon packet structure. + +![](img/photon-packet.png) + +The packet is made up of two parts: the header and the payload. The header contains exactly five bytes: "to" address, "from" address, packet ID, payload length, and the CRC. The payload *always* has at least one byte, either a command ID or a status. The payload can have optional further bytes. + +## Header Bytes + +### To Address + +This byte indicates which address the packet is intended for. This address value is equivalent to the slot addresses. + +Valid values are anywhere between `0x00` and `0xFF`. Address `0x00` is reserved for the host, and address `0xFF` is reserved for broadcast commands. + +### From Address + +This byte indicates which address the packet is coming from. This address value is equivalent to the slot addresses. + +Valid values are anywhere between `0x00` and `0xFF`. Address `0x00` is reserved for the host. + +### Packet ID + +The Packet ID is an identifying byte that allows the devices on the bus to keep track of requests. When a feeder responds to a command, it includes the Packet ID of the initiating packet. This allows the host to determine which packet the feeder is responding to. + +This byte is a value between `0x00` and `0xFF`. The host should increment this value for every command sent, and roll back to `0x00` once it reaches `0xFF`. + +### Payload Length + +The payload length is the number of bytes contained in the payload. This number will always be at least `0x01`, as each packet has at least a Command ID or Status. + +### CRC + +The CRC byte is a checksum calculated on the entire packet sans the checksum byte. The checksum can be calculated as shown below: + +JavaScript + +``` javascript +calcCRC(data){ + let crc = 0; + for(var i = 0; i> 8) & 0xFF; +} +``` + +C + +``` c +uint8_t crc8(uint8_t data, size_t len) { + uint32_t crc = 0; + + for (size_t i = 0; i < len; i++) { + crc ^= (data << 8); + for (size_t bit_n = 0; bit_n < 8; bit_n++) { + if (crc & 0x8000) { + crc ^= (0x1070 << 3); + } + crc <<= 1; + } + } + + return (uint8_t)(crc >> 8); +} +``` + +Once the CRC is calculated, it should be spliced into the packet in the appropriate location. The CRC should be recalculated and compared with the received CRC for every received packet to confirm data integrity. + +## Payload + +The first byte of the payload is always a Command ID when coming from the host, and always a Status when coming as a response from a feeder. The Command ID tells the feeder what action to perform or what information to send. The Status tells the host the status of the command. + +The rest of the payload is used for any other information that needs to be sent, depending on the situation. + +| Command Code | Name | +| ------ | ----------------------------- | +| `0x01` | Get Feeder ID | +| `0x02` | Initialize Feeder | +| `0x03` | Get Version | +| `0x04` | Move Feed Forward | +| `0x05` | Move Feed Backward | +| `0x06` | Move Feed Status | +| `0xbf` | Vendor Options | +| `0xc0` | Get Feeder Address | +| `0xc1` | Identify Feeder | +| `0xc2` | Program Feeder Floor | +| `0xc3` | Uninitialized Feeders Respond | + +| Status Code | Name | +| ----------- | ---------------------- | +| `0x00` | `OK` | +| `0x01` | `WRONG_FEEDER_ID` | +| `0x02` | `COULDNT_REACH` | +| `0x03` | `UNINITIALIZED_FEEDER` | +| `0x04` | `FEEDING_IN_PROGRESS` | +| `0x05` | `FAIL` | +| `0xFE` | `TIMEOUT` | +| `0xFF` | `UNKNOWN` | + +## Command IDs + +Each Command ID the host can send a feeder have certain payload requirements, and certain expected responses from the feeder. + +### GET_ID `0x01` + +| Send | | +| -------------------- | ------------ | +| Requires Initialized | NO | +| Addressing | UNICAST | +| Payload | NONE | + +| Receive | | | +| -------------------- | ------------ | ------- | +| Status | `OK` | 0 | +| Payload | 12 Byte UUID | 1-13 | + +GET_ID is used to get a feeder's UUID knowing only it's slot address. GET_ID is used mainly to scan the bus address space and see if a feeder is present in a slot, and get its UUID for initilizing. + +#### Example + +Send: +``` +[02] [00] [07] [01] [C0] [01] + | | | | | | + | | | | | Sending Command 0x01 means GET_ID + | | | | | + | | | | Checksum + | | | | + | | | Payload Length of 1 + | | | + | | Packet ID + | | + | From Address + | +To Address +``` + +Receive: +``` +[00] [02] [07] [13] [D7] [00] [02] [48] ..... [37] [30] + | | | | | | |_____________________| + | | | | | | | + | | | | | | | + | | | | | | 12 Byte UUID + | | | | | | + | | | | | Status 0x00 means OK + | | | | | + | | | | Checksum + | | | | + | | | Payload Length of 13 + | | | + | | Packet ID + | | + | From Address + | +To Address +``` + + + diff --git a/mkdocs.yml b/mkdocs.yml index f18a09729..1f1dfba08 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -138,6 +138,7 @@ nav: - Troubleshooting: feeders/8-troubleshooting/troubleshooting.md - Guides: + - Update LumenPnP Firmware: guides/update-firmware/index.md - Change Motor Current: guides/motor-current/index.md - Change Machine Speed: guides/machine-speed/index.md - Change Ring Light Brightness: guides/ring-light-settings/index.md @@ -152,6 +153,7 @@ nav: - Misc: - Backlash Compensation: misc/backlash-compensation/index.md - Automatic Toolchanger: misc/auto-toolchanger/index.md + - Design for LumenPnP: design-for-lumenpnp/index.md