armCtl/README.md

# armCtl

### Summary
A suite of software useful in experimenting with small robotic arms.  Use as a teaching framework with a low barrier to entry for robotics and programming.

### History
Whilst an expansive scope, the principal development and implementation happened over 3 days in the summer of 2019.


## Software Components
 1. An Arduino firmware to recieve commands and position the robot arm.
  * firmware/armCtl/armCtl.ino
 1. A streaming serial command & control protocol to communicate with the Arduino from a computer.
 1. A Python3 module that is a threaded serial reader/writer, and state machine for the arm.
  * robot.py
 1. An Antlr4 domain-specific scripting language for maneuvering the robot.
  * ArmControl.g4
 1. A Python3 implementation of that language for the Robot module.
  * ArmCtlListener.py
 1. A Python3 module to interface the scripting language to the robot module.  When called directly, this module also provides an interactive shell for the scripting language.
  * armCtl.py


## Hardware Components

This BOM is one possible configuration.  Substitute parts are available, and any servo controlled arm is acceptable.

| Part | Cost |
|------|------|
| [Arduino Uno](https://store.arduino.cc/usa/arduino-uno-rev3/) | $22 |
| [Arduino Sensor Shield V5](https://www.amazon.com/Sensor-Shield-Digital-Arduino-Duemilanove/dp/B01FDH8SM6/ref=sr_1_4?keywords=Arduino+Sensor+Shield+V5&qid=1564509416&s=gateway&sr=8-4)| $7.19 |
| [Power Supply 25W 5V 5A](https://www.mouser.com/ProductDetail/?qs=pqZ7J9Gt%2FmqXHOzlkOY2rg%3D%3D)| $9.50 |
| [6-Axis Desktop Robotic Arm](https://www.amazon.com/gp/product/B00UMOSQCI/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1) | $170 |


## Activities
 * Control the arm interactively.

```none
> ./armCtl.py
command# go jib 90
command# wait
command# go home
```

 * Script a simple sequence of moves.

```bash
# my_script.txt
go jib 90
wait
go home

> ./armCtl.py my_script.txt
```

 * Write a Python3 script for complex movements.

```python
#!/usr/bin/env python3
import armCtl as arm

arm.command("go jib 90")

arm.r.target = [90, 120, 10, 95, 90, 90]
arm.r.move()
while arm.r.isMoving():
    pass
print(arm.r.angle)
```

## Referance

### Scripting Commands
Multiple script commands given on the same line must be seperated with a semicolon (*;*).
#### go coordinates | axis_name vale | preset_name
Set target coordinates for the arm.  Movement will not begin until the command statement is complete
###### coordinates
Go to the coordinates given as *{value, value, value, value}*.  Values must be integers. Values may be given in either decimal or hexidecimal notation.  Omitted values will be accepted as *null* and will not effect the arm position.
###### axis_name value
Move the named axis to the given value.  Names must be defined in the configuration file as the intiger index of the axis in the command protocol.  Values must be integers. Values may be in decimal or hexidecimal notation.
###### preset_name
Move the robot to the named corrdinates defined in the configuration file.  Coordinates must be defined in decimal notation.
#### pause time
###### time
Do nothing for the length of time.
#### wait (time)
Wait for the arm to stop moving.  
###### time
If time is given, pause for that amout of time after movement has completed. If time is omitted, do the next command immediatly after movement stops.
#### pass
Do nothing.

### Shell Commands
#### exit
End the shell session.
#### quit
Same as exit.