| Name | pycro-hal JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | python module to drive a microprocessor HAL interface |
| upload_time | 2025-08-07 03:25:58 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
arduino
serial
interface
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
* website: <https://arrizza.com/pycro-hal.html>
* installation: see <https://arrizza.com/setup-common.html>
## Summary
A python interface to a microcontroller with a Hardware Abstraction Layer (HAL).
This module allows a python script to control an Arduino. It reads or writes to any of the Digital or Analog pins.
Currently only works with Arduino Nano.
See <https://arrizza.com/pycro> for the full communications protocol or the doc/comm_protocol.md.
## Future enhancements
* Double check it works cross-platform i.e. macOS and Windows
* Expand the functionality, e.g. allow ISP communications between two Arduinos to be controlled by the python script.
* Add additional support for Arduino shields. There probably is a need to have an "easy to add" interface to multiple
shields.
* Abstract out specific and common functions so that the same script (with minor changes) can be used on multiple or any
Arduino. If this goes well, it may be possible to abstract ot other microcontroller chips.
## Initial setup
* see doc/test_process.md for set of instructions to correctly setup the python venv, and to make sure all other
tools are installed. You can check by using ```./do_check```
* The Arduino you use must be flashed with <https://arrizza.com/pycro-arduino>
#### Nano breadboard
see <https://arrizza.com/img/pycro/pycro-nano-arduino.jpg> for a schematic.
* setup Nano on breadboard
* attach USB-C to Nano
* Nano GND pin to breadboard -ve
* Nano +5V pin to breadboard +ve
* setup a 10K potentiometer
* middle pin attached to Nano A7
* one other pin attached to breadboard -ve (Gnd)
* one other pin attached to breadboard +ve (5V)
* check with ```doit adc``` or ```doit graph``` (turning the pot, should change the voltage read)
* oScope for fastest GPIO cycling:
* gnd lead to breadboard -ve (Gnd)
* +ve lead to Nano D13
* check with ```doit gpio_fast``` (should see a square wave)
* oScope for PWM duty cycle:
* gnd lead to breadboard -ve (Gnd)
* +ve lead to Nano D5
* check with ```doit pwm``` (should see a square wave with a 50/50 duty cycle with a 1.024mS period)
* external LED:
* Nano D12 to 2k resistor
* other end of 2k resistor to LED long leg (+ve)
* LED short leg (-ve) to breadboard -ve (GND)
* check with ```doit gpio_write``` (LED should blink)
* Nano digital pins
* Nano D2 to breadboard +ve (5V)
* Nano D11 to breadboard +ve (5V)
* check with ```doit digport``` (D2 and D11 should be 1, others should be 0)
## Sample App
See sample/app.py for an example of how to use PycroHalInterface.
In short, there are 4 steps:
#### Step 1 set up serial port
Communication with the Arduino is UART/Serial. Specify that by setting the configuration:
```python
self._pycro.cfg.protocol = 'uart'
self._pycro.cfg.uart_port = '/dev/ttyUSB0'
```
* currently only the 'uart' protocol is recognized
* the uart_port must match the serial/uart port the Arduino is connected to.
#### Step 2 start the communications
```python
self._pycro.start()
```
Note: the Arduino sends 2 or 3 empty responses to ensure the communication channel is running correctly. If these stop
or fail or hang, then there is a communication issue that needs to be resolved.
#### Step 3 send a command and receive of a response
As an example, send a ping and receive the pong response.
```python
self._pycro.ping()
self._pycro.recv() # note: not all commands have a response.
```
See doc/comm_protocol.md for specific behaviors for all the possible commands.
You can do as many commands as you need in this step.
#### Stop communications
It is very good practice to cleanly terminate communications. Most OSs are pretty good at automatically cleaning up,
but it is worth the effort to close, shut down, and clean up any communications, threads etc. when the app closes.
```python
self._pycro.stop()
```
## Run it
* Power on the Arduino
* Check the comm port is connected
* run ./doit to run the app
```bash
ls /dev/ttyUSB* # on Ubuntu; other OSs are different
./doit # defaults to ping-pong
```
Typical output:
```text
00:00.001 App.run tests:ping
00:00.203 checking communications...
00:01.462 rx: 0000: 00 # two empty rsp automatically sent by Arduino
00:01.462 rx: 0000: 00
00:01.462 comm_ok: 1
00:01.462 comm_ok: 2
00:01.462 OK connection: 2 comm_ok rsp received; 14 loops
00:01.462 tx: 0000: 03 00 00 # tx a ping
00:01.465 rx: 0000: 03 01 01 # rx a pong
00:01.465 tx: 0000: 03 00 00 # ping again
00:01.468 rx: 0000: 03 01 01 # pong again
```
The current app has the following CLI:
```bash
./doit ping # ping-pong
./doit version # get microcontroller version
./doit gpio_read # read a digital pin; currently set to D10
./doit digport # read all digital pins
./doit gpio_write # write a digital ping; currently set to D12
./doit fast_gpio # write a high/low sequence to a pin as quickly as possible; currently set to D13 = internal LED
./doit adc # read the voltage an analog pin; currently A7
./doit graphic # show a dynamically updated plot of voltages from adc
./doit logger_off # test turning off the logger and turning it back on again
./doit pwm # set PWM on digital pin; currently D5
./doit servo # test servo control; currently on D6
./doit adhoc # do an adhoc test as implemented on the microcontroller; currently an echo
./doit dev # used for dev purposes
./doit all # run all of these (except dev)
```
## ADC notes
Note: to get accurate values in ```./doit adc``` you must set the supply voltage correctly
```python
# in app.py run()
# my USB port supplies 4.69 volts; measure yours from the GND pin to the +5V pin using a multimeter
self._pycro.supply_voltage = 4.69
```
## PWM notes
* When the serial port is disconnected, the pin reverts back to 0 (non-pulsing).
* enter an integer to bump the duty cycle up / down from the default of 127
```text
./doit pwm
<skip>
00:01.463 pwm: setting to: 127
00:01.463 tx: 0000: 05 00 07 05 7F
pwm: press +, - or q to quit: -120 <=== subtract 120 from 127
00:03.337 pwm: setting to: 7
00:03.337 tx: 0000: 05 00 07 05 07
pwm: press +, - or q to quit: -10
00:06.338 WARN pwm: new val is too low: 7 + -10 => -3 <=== went too far
00:06.338 tx: 0000: 05 00 07 05 07
pwm: press +, - or q to quit: +250 <=== the "+" is optional
00:36.457 WARN pwm: new val is too high: 7 + 250 => 257
```
## servo notes
I used an HS-311 servo, see <https://www.servocity.com/hs-311-servo/> for specs. Your servo may require different
settings.
* Voltage Range: 4.8V - 6.0V
* Max PWM Signal Range: 575-2460 uSec
* Max Rotation: 202 degrees
* I used a separate power supply that can handle 5V up to 1A with a 100 uF capacitor,
see <https://docs.arduino.cc/learn/electronics/servo-motors/>
* It uses similar +/- commands as PWM but these are for degrees (0 - 202), not duty cycle
Raw data
{
"_id": null,
"home_page": null,
"name": "pycro-hal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "\"J. Arrizza\" <cppgent0@gmail.com>",
"keywords": "arduino, serial, interface",
"author": null,
"author_email": "\"J. Arrizza\" <cppgent0@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/f1/f00914b0636174ae8422b9eff71d075f14a08e3fa4352ed85d74eec3bf53/pycro_hal-0.2.0.tar.gz",
"platform": null,
"description": "* website: <https://arrizza.com/pycro-hal.html>\n* installation: see <https://arrizza.com/setup-common.html>\n\n## Summary\n\nA python interface to a microcontroller with a Hardware Abstraction Layer (HAL).\n\nThis module allows a python script to control an Arduino. It reads or writes to any of the Digital or Analog pins.\n\nCurrently only works with Arduino Nano.\n\nSee <https://arrizza.com/pycro> for the full communications protocol or the doc/comm_protocol.md.\n\n## Future enhancements\n\n* Double check it works cross-platform i.e. macOS and Windows\n* Expand the functionality, e.g. allow ISP communications between two Arduinos to be controlled by the python script.\n* Add additional support for Arduino shields. There probably is a need to have an \"easy to add\" interface to multiple\n shields.\n* Abstract out specific and common functions so that the same script (with minor changes) can be used on multiple or any\n Arduino. If this goes well, it may be possible to abstract ot other microcontroller chips.\n\n## Initial setup\n\n* see doc/test_process.md for set of instructions to correctly setup the python venv, and to make sure all other\n tools are installed. You can check by using ```./do_check```\n* The Arduino you use must be flashed with <https://arrizza.com/pycro-arduino>\n\n#### Nano breadboard\n\nsee <https://arrizza.com/img/pycro/pycro-nano-arduino.jpg> for a schematic.\n\n* setup Nano on breadboard\n* attach USB-C to Nano\n* Nano GND pin to breadboard -ve\n* Nano +5V pin to breadboard +ve\n* setup a 10K potentiometer\n * middle pin attached to Nano A7\n * one other pin attached to breadboard -ve (Gnd)\n * one other pin attached to breadboard +ve (5V)\n * check with ```doit adc``` or ```doit graph``` (turning the pot, should change the voltage read)\n* oScope for fastest GPIO cycling:\n * gnd lead to breadboard -ve (Gnd)\n * +ve lead to Nano D13\n * check with ```doit gpio_fast``` (should see a square wave)\n* oScope for PWM duty cycle:\n * gnd lead to breadboard -ve (Gnd)\n * +ve lead to Nano D5\n * check with ```doit pwm``` (should see a square wave with a 50/50 duty cycle with a 1.024mS period)\n* external LED:\n * Nano D12 to 2k resistor\n * other end of 2k resistor to LED long leg (+ve)\n * LED short leg (-ve) to breadboard -ve (GND)\n * check with ```doit gpio_write``` (LED should blink)\n* Nano digital pins\n * Nano D2 to breadboard +ve (5V)\n * Nano D11 to breadboard +ve (5V)\n * check with ```doit digport``` (D2 and D11 should be 1, others should be 0)\n\n## Sample App\n\nSee sample/app.py for an example of how to use PycroHalInterface.\n\nIn short, there are 4 steps:\n\n#### Step 1 set up serial port\n\nCommunication with the Arduino is UART/Serial. Specify that by setting the configuration:\n\n```python\nself._pycro.cfg.protocol = 'uart'\nself._pycro.cfg.uart_port = '/dev/ttyUSB0'\n```\n\n* currently only the 'uart' protocol is recognized\n* the uart_port must match the serial/uart port the Arduino is connected to.\n\n#### Step 2 start the communications\n\n```python\nself._pycro.start()\n```\n\nNote: the Arduino sends 2 or 3 empty responses to ensure the communication channel is running correctly. If these stop\nor fail or hang, then there is a communication issue that needs to be resolved.\n\n#### Step 3 send a command and receive of a response\n\nAs an example, send a ping and receive the pong response.\n\n```python\nself._pycro.ping()\nself._pycro.recv() # note: not all commands have a response.\n```\n\nSee doc/comm_protocol.md for specific behaviors for all the possible commands.\n\nYou can do as many commands as you need in this step.\n\n#### Stop communications\n\nIt is very good practice to cleanly terminate communications. Most OSs are pretty good at automatically cleaning up,\nbut it is worth the effort to close, shut down, and clean up any communications, threads etc. when the app closes.\n\n```python\nself._pycro.stop()\n```\n\n## Run it\n\n* Power on the Arduino\n* Check the comm port is connected\n* run ./doit to run the app\n\n```bash\nls /dev/ttyUSB* # on Ubuntu; other OSs are different\n\n./doit # defaults to ping-pong\n```\n\nTypical output:\n\n```text\n00:00.001 App.run tests:ping\n00:00.203 checking communications...\n00:01.462 rx: 0000: 00 # two empty rsp automatically sent by Arduino \n00:01.462 rx: 0000: 00 \n00:01.462 comm_ok: 1\n00:01.462 comm_ok: 2\n00:01.462 OK connection: 2 comm_ok rsp received; 14 loops\n00:01.462 tx: 0000: 03 00 00 # tx a ping \n00:01.465 rx: 0000: 03 01 01 # rx a pong\n00:01.465 tx: 0000: 03 00 00 # ping again\n00:01.468 rx: 0000: 03 01 01 # pong again \n```\n\nThe current app has the following CLI:\n\n```bash\n./doit ping # ping-pong\n./doit version # get microcontroller version\n./doit gpio_read # read a digital pin; currently set to D10\n./doit digport # read all digital pins\n./doit gpio_write # write a digital ping; currently set to D12\n./doit fast_gpio # write a high/low sequence to a pin as quickly as possible; currently set to D13 = internal LED\n./doit adc # read the voltage an analog pin; currently A7\n./doit graphic # show a dynamically updated plot of voltages from adc\n./doit logger_off # test turning off the logger and turning it back on again\n./doit pwm # set PWM on digital pin; currently D5\n./doit servo # test servo control; currently on D6 \n./doit adhoc # do an adhoc test as implemented on the microcontroller; currently an echo\n./doit dev # used for dev purposes\n\n./doit all # run all of these (except dev)\n```\n\n## ADC notes\n\nNote: to get accurate values in ```./doit adc``` you must set the supply voltage correctly\n\n```python\n# in app.py run()\n# my USB port supplies 4.69 volts; measure yours from the GND pin to the +5V pin using a multimeter\nself._pycro.supply_voltage = 4.69\n```\n\n## PWM notes\n\n* When the serial port is disconnected, the pin reverts back to 0 (non-pulsing).\n* enter an integer to bump the duty cycle up / down from the default of 127\n\n```text\n./doit pwm\n<skip>\n00:01.463 pwm: setting to: 127\n00:01.463 tx: 0000: 05 00 07 05 7F \npwm: press +, - or q to quit: -120 <=== subtract 120 from 127\n00:03.337 pwm: setting to: 7\n00:03.337 tx: 0000: 05 00 07 05 07 \npwm: press +, - or q to quit: -10\n00:06.338 WARN pwm: new val is too low: 7 + -10 => -3 <=== went too far \n00:06.338 tx: 0000: 05 00 07 05 07 \npwm: press +, - or q to quit: +250 <=== the \"+\" is optional\n00:36.457 WARN pwm: new val is too high: 7 + 250 => 257\n```\n\n## servo notes\n\nI used an HS-311 servo, see <https://www.servocity.com/hs-311-servo/> for specs. Your servo may require different\nsettings.\n\n* Voltage Range: 4.8V - 6.0V\n* Max PWM Signal Range: 575-2460 uSec\n* Max Rotation: 202 degrees\n* I used a separate power supply that can handle 5V up to 1A with a 100 uF capacitor,\n see <https://docs.arduino.cc/learn/electronics/servo-motors/>\n* It uses similar +/- commands as PWM but these are for degrees (0 - 202), not duty cycle \n",
"bugtrack_url": null,
"license": null,
"summary": "python module to drive a microprocessor HAL interface",
"version": "0.2.0",
"project_urls": {
"Download": "https://bitbucket.org/arrizza-public/pycro-hal/get/master.zip",
"Source": "https://bitbucket.org/arrizza-public/pycro-hal/src/master",
"Website": "https://arrizza.com/pycro-hal"
},
"split_keywords": [
"arduino",
" serial",
" interface"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0f1f00914b0636174ae8422b9eff71d075f14a08e3fa4352ed85d74eec3bf53",
"md5": "e002b55359776e6af3f5bc1da3b15b0b",
"sha256": "fd7104938bb314f2b75c72741b1d54631f761381157d4411f68139f51e9218cd"
},
"downloads": -1,
"filename": "pycro_hal-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e002b55359776e6af3f5bc1da3b15b0b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15783,
"upload_time": "2025-08-07T03:25:58",
"upload_time_iso_8601": "2025-08-07T03:25:58.578598Z",
"url": "https://files.pythonhosted.org/packages/a0/f1/f00914b0636174ae8422b9eff71d075f14a08e3fa4352ed85d74eec3bf53/pycro_hal-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 03:25:58",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "arrizza-public",
"bitbucket_project": "pycro-hal",
"lcname": "pycro-hal"
}
