Pulse program template

Template to create Python programs for Pulse Program Player.

Concept

A cookiecutter template for Pulse Robotic Arm Program Player. The main idea behind this project is to create easy to use development environment with predefined structure so that it gives an opportunity to create, test, deploy and run programs for Pulse Robotic Arm.

Requirements

Python 3.5+

Installation

Python 3.5+ required (on Debian-based linux run sudo apt-get install python3-dev python3-venv python3-pip)
python3 -m pip install cookiecutter --user
python3 -m cookiecutter https://github.com/rozum-robotics/pulse-program-template will result in several prompts to be filled (see params) (change the link when published)
cd {{cookiecutter.project_name}} (project_name is filled during template initialization)
python3 -m venv venv will create virtual environment for the project
source venv/bin/activate will activate virtual environment
pip install -e . -r requirements/development.txt will install development requirements.

Windows specific note: Use python instead of python3 in commands and make sure it is added to PATH.

Cookiecutter params

{
    "project_name": "helloworld", // name of the project folder and the package inside.
    // MUST be a valid python module/package name, see: https://docs.python-guide.org/writing/structure/#modules 
    "email": "dev@rozum.com", // optional email
    "author": "Rozum Robotics", // optional author
    "url": "https://rozum.com", // optional url
    "version": "0.0.1", // initial version of the project
    "pulse_api_version": "1.6.0" //pulse-api version to use in the project
}

Initial project structure

After completing the installation steps, the project of the following structure is created:

project_name - folder containing project and development environment.
- project_name - folder containing source code.
  - __init__.py - identificates that the folder is python package.
  - main.py - should be used to run program locally during development.
  - program.py - is used in main.py and when the program is executed on the robot side. IMPORTANT: Do not rename this file.
- requirements - folder containing development/production requirements.
  - development.txt - is used for development requirements.
  - production.txt - is used for production requirements. This file would be used on the robot side to install the dependencies needed for the program to be executed properly.
- MANIFEST.in - file that contains rules about what files should be included into built package.
- README.md - is used to place any ne explanatory information about the project.
- setup.py - is used to build distribution package from source files.
- upload.py - is used to build and upload distribution to the robot.

Tip: you should place your modules/packages in the package_name/package_name folder (near the __init__.py).

program.py structure

There is a predefined Instance class that is used to store the program logic. There are predefined methods where you should place your logic.

IMPORTANT: You must not rename or remove mentioned methods and class name. Such actions would result in runtime errors. If you do not need some methods, put the pass keyword inside and leave them blank.

__init__ and __enter__ - used for the program instance initialization. Should not be modified.
__exit__ - used for program instance deinitialization. Invokes the on_error() method passing the exception value if it is present.
before_all() - will be executed once before the the other methods. It is a good place to put initialization logic. For example, set the starting pose/position for the robot or enable necessary devices
before_each() - will be executed before each iteration. It is a good place to put starting logic. For example, ask the robot to go to the first point in iteration and/or enable the tooling installed.
execute() - represents one iteration. Place any logic that is needed to be done during iteration here.
after_each() - will be executed after each iteration. It is a good place to put iteration finalization logic. For example, ask the robot to go to the last point in iteration and/or disable the tooling installed.
after_all() - will be executed once after the user stops the program. It is a good place to put complete finalization logic. For example, ask the robot to switch off the devices and go to the final position.
on_error() - will be executed on any runtime error that is not caught by the user code. It is a good place for logic that would provide safe deitialization of the robot and devices.

Execution and deployment

Local execution

To run the program locally, after the template is filled with necessary logic, use the following command (remember to activate the virtual environment):

python3 -m project_name.main -i number_of_iterations --robot-addr robot_addr_goes_here

For example you want the robot that is located at the known network address (e.g. 192.168.0.24) perform two iterations using code from your project (named some_program, for example purposes). Use the following command to achieve this behavior:

python3 -m some_program.main -i 2 --robot-addr http://192.168.0.24:8081

This should result in the following execution sequence:

before_all
Repeat 2 times:
- before_each
- execute
- after_each
after_all
If there are any runtime errors during the execution on_error is called

Program deployment

Lets assume that robot is located at the known network address (e.g. 192.168.0.24). You tested the program locally and you want to deploy program on robot for future usage. You can do this using the following command (remember to activate the virtual environment):

python3 upload.py 192.168.0.24

Notice that script would ask you a sandbox password. The default password is sandbox.

If you need to upload program to the port that is not the default one (e.g. 2222, instead of the default one - 22), use the following command:

python3 upload.py 192.168.0.24 --port 2222

If there are any errors during upload, you can enable verbose logging, by passing the --verbose parameter to the command:

python3 upload.py 192.168.0.24 --verbose

If you still can not deal with the error - contact the developers/support and attach the upload.log file which can be generated by passing the --dump-log parameter to the command. Also, please, write the actions that took part before. Example command to dump detailed log:

python3 upload.py 192.168.0.24 --verbose --dump-log

Examples

There is an examples folder in repository. It contains pre-initialized templates.

Minimal requirements

Python3 (3.5+ version) is installed in your system
It is possible to initialize python virtual environment. It means:
1. On Linux: python3-venv package is installed
2. On Windows: python is added to PATH during installation or manually and virtualenv package is installed
3. On MacOS: check that you can create venv using the python3 -m venv venv in terminal or use this guide

How to run pre-initialized template

Download archive (e.g. example_170.zip, compatible with Pulse-Desk 1.7.0)
Unzip it into working directory
Open terminal and navigate into unzipped folder
Initialize virtual environment: python3 -m venv venv or, for Windows, python -m venv venv
Activate virtual environment: source venv/bin/activate or, for Windows cmd/powershell, <venv>\Scripts\activate.bat/PS C:\> <venv>\Scripts\Activate.ps1
Install development requirements: pip install -r requirements/development.txt
Follow the upload guide above
Run the program from Pulse Program Player UI.

rozum-robotics/pulse-program-template