Skip to content

Installation

Jump to bottom
Dale Thomas edited this page Nov 27, 2024 · 14 revisions

Electrical Installation

Electrical installation will depend on which robot you are using. I will include detailed instructions for the AR4 from Annin Robotics as it is the robot that was used to develop ArfBotOS. Refer to the AR4 integration documentation located here. As other robots are integrated with ArfBotOS, instructions will be added for them as well. Do you have a suggestion for the next robot?

EtherCAT

To communicate with all devices (I/O and Robot) we are using EtherCAT communication. To facilitate this on the AR4, we are using the EVB-LAN9252-SPI development board from Microchip. You can purchase this directly from Microchip for $79.00 USD.

This board using SPI to communicate to the Teensy microcontroller. For this, we will need to use SPI pins 10, 11, 12, and 13 on the Teensy and move some of the stock AR4 wiring to other GPIO.

For digital input and output, there are two options. The first option is using industrial IO cards from Beckhoff. A EK1100 EtherCAT Coupler, a EL1809 16 Channel 24v Input, and a EL2809 16 Channel 24v Output.

The second option is using a Teensy controller and EVB-LAN9252-SPI EtherCAT Slave. For this option, you will need to flash firmaware on bothe the Teensy and the EVB-LAN9252-SPI.

The PLC is programmed to recognize which IO is enabled in the device tree and automatically map that according to the table below.

Before downloading the code to the PLC, Right-click on the IO and enable the one which you wish to use and disable the other one. TODO: this will be automated in the future using Python.
menu

I/O Mapping

There are 16 total digital inputs and 16 total digital outputs. These are mapped to the I/O devices according to which option is chosen (IoOption1 or IoOption2) as follows:

input IoOption1 IoOption2 output IoOption1 IoOption2
0 EL1809 0 Teensy 0 0 EL2809 0 Teensy 23
1 EL1809 1 Teensy 1 1 EL2809 1 Teensy 22
2 EL1809 2 Teensy 2 2 EL2809 2 Teensy 21
3 EL1809 3 Teensy 3 3 EL2809 3 Teensy 20
4 EL1809 4 Teensy 4 4 EL2809 4 Teensy 19
5 EL1809 5 Teensy 5 5 EL2809 5 Teensy 18
6 EL1809 6 Teensy 6 6 EL2809 6 Teensy 16
7 EL1809 7 Teensy 7 7 EL2809 7 Teensy 15
8 EL1809 8 Teensy 8 8 EL2809 8 Teensy 14
9 EL1809 9 Teensy 9 9 EL2809 9 Teensy 41
10 EL1809 10 Teensy 24 10 EL2809 10 Teensy 40
11 EL1809 11 Teensy 25 11 EL2809 11 Teensy 39
12 EL1809 12 Teensy 26 12 EL2809 12 Teensy 38
13 EL1809 13 Teensy 27 13 EL2809 13 Teensy 37
14 EL1809 14 Teensy 28 14 EL2809 14 Teensy 36
15 EL1809 15 Teensy 29 15 EL2809 15 Teensy 35

Camera

note: ArfBot vision can run on a dedicated Raspberry Pi. This is recommended for performance reasons. If this option is chosen, this step can be performed on the Raspberry Pi dedicated for vision.

For the vision system, we will use the Arducam and OpenCV Python libraries.

For this, we will need the following components:

  • Arducam for Raspberry Pi HQ Camera 12.3MP IMX477
  • Arducam CSI to HDMI Adapter Board
  • Arducam CS-Mount Lens Kit
  • HDMI cable long enough to reach from the Raspberry to the camera

Software Installation

Raspberry Pi OS Installation and Configuration

Needed:

  • development pc running Windows
  • Raspberry Pi 4 with 4gb ram or greater (CODESYS now supports Raspberry Pi 5 but this has not been test with ArfBotOS)
  • 16gb micro sd card or larger (smaller makes backups easier)
  • sd card to usb adapter (or other solution for connecting sd card to pc)

Imaging the Disk:

  1. install/open Raspberry Pi imager. https://www.Raspberrypi.com/software/
  2. insert sd card into dev pc
  3. choose Raspberry Pi device from dropdown
  4. choose operating system from dropdown (must be Raspberry Pi os 32-bit to make use of codesys multi-core) Note: choosing the headless option is recommended for performance reasons.
  5. choose storage (sd card you inserted earlier)
  6. press ctrl + shift + x to open advanced settings (depending on the version of Raspberry Pi imager you may get to this by choosing next and 'edit settings' from the prompt)
  7. on the GENERAL tab set the hostname to 'ArfBot' (recommended but not required).
  8. set username and password of the default user (recommend 'ArfBot' for username) Note: remember this password as you will need it many times in the future!.
  9. set the SSID and password of your wifi network.
  10. on the SERVICES tab select 'Enable SSH' and 'Use password authentication' (this will allow connecting remotely to ArfBotOS via command line).
  11. click SAVE (then YES if you were prompted to apply OS customization settings).
  12. follow the remaining prompts to start writing to the disk. this will take a bit of time.

Booting Up and Connecting SSH

  1. insert sd card into Raspberry Pi and power it up. if the settings entered in the Raspberry Pi imager are correct, the pi should connect to your wifi already. if not begin troubleshooting there.
  2. open up a command prompt on your development pc and type ssh ArfBot@ArfBot.local. Note: the format is ssh user@host. if there are issues here, you may need to use the ip address of your pi like ssh user@192.168.1.1.
  3. after the security prompt and entering your password, you should be connected.

Backing Up The SD Card

  1. plug a new sd card into pi. (make sure card is identical size and brand or make it larger if different brand)
  2. run this command: sudo dd bs=4M if=/dev/mmcblk0 of=/dev/sda to copy all contents from the source SD card to the target.
  3. it will take a long time. just wait. will see activity lights on pi.
  4. boot with new card to test if the copy was successful.

references:

Configuring Arducam

note: ArfBot vision can run on a dedicated Raspberry Pi 5. This is recommended for performance reasons. If this option is chosen, this step can be performed on the Raspberry Pi 5 dedicated for vision.

  1. from an SSH session open the boot config file sudo nano /boot/firmware/config.txt
  2. add these lines to the config file camera_auto_detect=0 and dtoverlay=imx477 (under [ALL])
  3. type ctrl + x then y then enter to save and close the config file in nano.

references:

Installing OpenCV

note: ArfBot vision can run on a dedicated Raspberry Pi 5. This is recommended for performance reasons. If this option is chosen, this step can be performed on the Raspberry Pi 5 dedicated for vision.

  1. from an SSH seesion run this command to install OpenCV sudo apt-get install python3-opencv
  2. verify installation and version by typing the following commands. python import cv2 as cv print(cv.__version__) TODO: is this command needed? pip install "picamera[array]"

references:

Install Vision Command Service

note: ArfBot vision can run on a dedicated Raspberry Pi 5. This is recommended for performance reasons. If this option is chosen, this step can be performed on the Raspberry Pi 5 dedicated for vision.

  1. run this command to make the service file and edit in nano sudo nano /etc/systemd/system/PyServer.service
  2. copy and paste the following into the file:
[Unit]
Description=Runs Python Scripts Sent By Client
After=multi-user.target

[Service]
Type=simple
Restart=always
StandardOutput=append:/var/opt/codesys/PlcLogic/Application/Vision/VisionLog.txt
StandardError=append:/var/opt/codesys/PlcLogic/Application/Vision/VisionErrorLog.txt
ExecStart=/usr/bin/python /var/opt/codesys/PlcLogic/Application/Vision/PyServer.py

[Install]
WantedBy=multi-user.target
  1. type ctrl + x then y then enter to save and close the config file in nano.
  2. copy the following files to /var/opt/codesys/PlcLogic/Application/Vision/:
  • /ArfbotOS/OpenCV/SocketServer/PyServer.py
  • /ArfbotOS/OpenCV/ImageCapture/CaptureImage.py
  • /ArfbotOS/OpenCV/FastTemplateMatching/FastTemplateMatching.py
  • /ArfbotOS/OpenCV/FastTemplateMatching/cal.yaml
  • /ArfbotOS/OpenCV/FastTemplateMatching/roi.yaml
  • /ArfbotOS/OpenCV/CameraCalibration/CalibrateCamera.py (hint: if you are copying from Windows you can use this command scp -r <local directory> user@host.host:<remote> from Windows command prompt. You may also need to make the directories if they do not exist with the following command in bash sudo mkdir -p /var/opt/codesystemp/PlcLogic/Application/Vision/. You may also need to set the owner of the directories before you are able to copy over to them with this command in bash sudo chown -R <user> /var/opt/codesys.)
  1. run the following commands to start the service.
  • sudo systemctl daemon-reload
  • sudo systemctl enable PyServer.service
  • sudo systemctl start PyServer.service (optional)
  • sudo systemctl status PyServer.service (optional - will see failed here if script not installed)

references:

Install Vision Web Service

note: ArfBot vision can run on a dedicated Raspberry Pi. This is recommended for performance reasons. If this option is chosen, this step can be performed on the Raspberry Pi dedicated for vision.

  1. run the following commands to install flask:
  • sudo pip install flask --break-system-packages TODO: install this in a virtual environment instead.
  • sudo pip install flask-wtf --break-system-packages TODO: install this in a virtual environment instead.
  • sudo pip install flask-sqlalchemy (optional)
  • sudo pip install flask-migrate (optional)
  1. run this command to make the service file and edit in nano sudo nano /etc/systemd/system/VisionWeb.service
  2. copy and paste the following into the file:
[Unit]
Description=Hosts a web server for the vision application
After=multi-user.target

[Service]
Type=simple
Restart=always
Environment=FLASK_APP=vision.py
WorkingDirectory=/var/opt/codesys/PlcLogic/Application/Vision/VisionWebServer
ExecStart=/usr/bin/flask run -h arfbot.local -p 5000

[Install]
WantedBy=multi-user.target
  1. type ctrl + x then y then enter to save and close the config file in nano.
  2. copy the ArfBotOS/OpenCV/VisionWebServer folder to /var/opt/codesys/PlcLogic/Application/Vision/VisionWebServer. (hint: if you are copying from Windows you can use this command scp -r <local directory> user@host.host:<remote> from Windows command prompt. You may also need to make the directories if they do not exist with the following command in bash sudo mkdir -p /var/opt/codesystemp/PlcLogic/Application/Vision/. You may also need to set the owner of the directories before you are able to copy over to them with this command in bash sudo chown -R <user> /var/opt/codesys.)
  3. run the following commands to start the service.
  • sudo systemctl daemon-reload
  • sudo systemctl enable VisionWeb.service
  • sudo systemctl start VisionWeb.service (optional)
  • sudo systemctl status VisionWeb.service (optional - will see failed here if script not installed)
  1. restart using the following command sudo reboot now.
  2. test the service is working by navigating to this url from a web browser on your network arfbot.local:5000.

references:

Install Controller Service

  1. run the following command to clone pydualsense to your Raspberry Pi: git clone https://github.com/flok/pydualsense (this will make the next step easier) (note: there is a bug in the original pydualsense. until that is fixed you will need to copy some files from my repository to get the controller working. more on that later.)
  2. run the following commands to install pydualsense:
  • sudo cp pydualsense/70-ps5-controller.rules /etc/udev/rules.d (note the path to the rules file is where you cloned the repo in step 1)
  • sudo udevadm control --reload-rules
  • sudo udevadm trigger
  • sudo apt install libhidapi-dev
  • sudo pip install --upgrade pydualsense --break-system-packages TODO: install this in a virtual environment instead.
  1. run this command to make the service file and edit in nano sudo nano /etc/systemd/system/DualSenseController.service
  2. copy and paste the following into the file:
[Unit]
Description=Hosts a socket server for connecting to a Playstation DualSense controller
After=multi-user.target

[Service]
Type=simple
Restart=always
StandardOutput=append:/var/opt/codesys/PlcLogic/Application/Controller/ControllerLog.txt
StandardError=append:/var/opt/codesys/PlcLogic/Application/Controller/ControllerErrorLog.txt
ExecStart=/usr/bin/python /var/opt/codesys/PlcLogic/Application/Controller/DualSenseServer.py

[Install]
WantedBy=multi-user.target
  1. type ctrl + x then y then enter to save and close the config file in nano.
  2. run the following commands to start the service. (note if you are following along the installation in chronological order, then we have not installed the python scripts yet and as such the service will fail. we will install them later but we want to enable the service here at least)
  • sudo systemctl daemon-reload
  • sudo systemctl enable DualSenseController.service
  • sudo systemctl start DualSenseController.service (optional)
  • sudo systemctl status DualSenseController.service (optional - will see failed here if script not installed)

special instruction:

There is a bug in flok's version of pydualsense. Until that is fixed, please clone my repo https://github.com/dalethomas81/pydualsense and copy the pydualsense folder over to /var/opt/codesys/PlcLogic/Application/Controller. Update: as of today, this fix has been merged into the dev branch of flok's repo. hopefully this will get merged into the next release.

references:

Connecting DualSense Playstation Controller

  1. run the following command to open Bluetooth control: bluetoothctl
  2. at the the [bluetooth]# prompt enter these commands: pairable on agent on default-agent scan on
  3. put the DualSense controller in paring mode by holding down the PS and Share buttons at the same time until the light around the trackpad starts flashing.
  4. at the [Bluetooth]# prompt wait for a message that looks like this [NEW] Device 12:23:34:45:56:67 devicename
  5. copy the mac address (from the above message) and enter this command to pair the controller (hint: it may be handy to type scan off to make the messages stop while you copy the mac address) pair 12:23:34:45:56:67
  6. you will see a message asking to allow control. type yes to finish pairing.
  7. enter the following command to allow the controller to connect automatically: trust 12:23:34:45:56:67
  8. enter exit to leave bluetooth control.

notes:

  • The controller will work connected via USB as well in the event that bluetooth is not working.
  • Eventually, I would like to get UI for this one the HMI.

references:

Installing CODESYS

CODESYS Development and Runtime

  1. download CODESYS dev environment 64-bit 3.5.20.3 from the CODESYS store and install it.
  2. from the Start menu of Windows open the CODESYS Installer and import the configuration located here ArfBotOS/Codesys/ArfBot.installation-config to install all of the required CODESYS software for ArfBot.
  3. open the CODESYS dev environment and from the Tools menu choose Update Raspberry Pi.
  4. from the Raspberry Pi panel enter the username and password of the user you created when you imaged the Raspberry Pi.
  5. enter the ip address of your Raspberry Pi.
  6. select Install to install the CODESYS runtime onto the Raspberry Pi.
  7. when prompted make sure Multicore 32-bit (ARMv7) is selected and click Close to configure the runtime. otherwise select Change.
  8. when prompted to install the gateway click Yes.

CODESYS Libraries

  1. open the Library Manager from the Devices tree.
  2. click on Download Missing Libraries in the top of the window and follow the prompts until all libraries are installed.
  3. open Device Respository from the Tools menu.
  4. click on the Install button and choose all of the files located in Resources/Device Description Files.

ArfBotOS CODESYS Project On The Raspberry Pi

  1. open ArfBot.project in CODESYS from ArfBotOS/Codesys (if prompted to update any libraries select 'Do Not Update' for each selection unless you know what you are doing)
  2. from the Build menu select Generate Code to compile. (cross your fingers)
  3. from the device tree, double-click on 'Device' and open the 'Communication Settings' tab.
  4. type in the ip address of the Raspberry Pi and hit enter. this will establish a connection to the gateway on the controller. (note that if you are having connectivity issues here you may have a different version of the runtime installed vs the gateway. you can check this by using the 'Update Raspberry Pi' and 'Update Edge Gateway' from the Tools menu)
  5. if the project built successfully and a connection to the gateway is established, open the Online menu and select 'Multiple Download...' to download the code to the controller. keep the default selections and press 'OK'
  6. during download, CODESYS will install necessary script files in the /var/opt/codesys/PlcLogic/Application/Vision directory (this is why the services we installed earlier would fail). there are 2 files and 1 directory that you will have to manually copy over to get vision working. note: if using a separate dedicated Raspberry Pi for vision, you will copy all vision files to that Raspberry Pi
  7. from the CODESYS development environment, double-click on Device and from the Files tab find the cal.yaml and roi.yaml files located in the ArfBot repository and copy them to the PlcLogic/Application/Vision directory. they can be found in the ArfBot/OpenCV/CameraCalibration and ArfBot/OpenCV/FastTemplateMatching folders, respectively. these files have initial values and will be dynamically generated later.
  8. next, copy the ArfBot/OpenCV/VisionWebServer directory over to the /var/opt/codesys/PlcLogic/Application/Vision directory.
  9. next, create a new directory in PlcLogic/Application/Vision called Templates.

Configuring CODESYS To Run Commands In Linux

  1. run this command to open the CODESYS Control config file and edit in nano sudo nano /etc/CODESYSControl.cfg
  2. copy and paste the following into the file:
[SysProcess]
Command=AllowAll
  1. type ctrl + x then y then enter to save and close the config file in nano.
  2. perform the same actions as above for the user file sudo nano /etc/CODESYSControl_User.cfg (note this file will already have an entry for SysProcess. You will need to over write it with this new entry)

CODESYS licensing

  1. You will need these 4 licenses (total $917.00USD):
  1. CODESYS licenses are married to hardware and cannot be transferred. Meaning that if your Raspberry Pi dies, you will need to purchase licenses again. Optionally, you can purchase the CODESYS key that will allow you to assign the license to the key and move the license around to other controllers (highly recommended!). Note that CODESYS will charge $41.99USD for shipping the key to you. CODESYS Key
notes:
  • CODESYS uses application specific licenses for very high granularity of features. While this has its advantages, it does make figuring out what license you need for your project difficult.
references:

Installing Arduino

The pulsing of the stepper drives and the reading of the encoders is all handled with the Teensy board running Arduino compiled C++ code. This information is passed to and from the Raspberry Pi via EtherCAT where the information is processed in the the CODESYS motion control libraries.

To compile and upload the Arduino code to the Teensy board, you will need to install 2 pieces of software on your development PC. The Arduino IDE found here and the Teensyduino add-on using the instructions found here.

You will also need to install the digitalWriteFast library using the library manager of Arduino.

Clone this wiki locally