Skip to content

Commit a7e13b2

Browse files
brainelectronicsbrainelectronics
authored
Merge pull request brainelectronics#28 from brainelectronics/feature/create-test-framework
2 parents ea37dc2 + 5332131 commit a7e13b2

File tree

13 files changed

+699
-64
lines changed

13 files changed

+699
-64
lines changed

‎.github/workflows/release.yml‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@ on:
99
- develop
1010

1111
permissions:
12-
contents: read
12+
contents: write
1313

1414
jobs:
1515
deploy:
1616
runs-on: ubuntu-latest
1717
steps:
1818
- name: Checkout
19-
uses: actions/checkout@v2
19+
uses: actions/checkout@v3
2020
- name: Set up Python
2121
uses: actions/setup-python@v3
2222
with:
@@ -41,3 +41,16 @@ jobs:
4141
skip_existing: true
4242
verbose: true
4343
print_hash: true
44+
- name: 'Create changelog based release'
45+
uses: brainelectronics/changelog-based-release@v1
46+
with:
47+
# note you'll typically need to create a personal access token
48+
# with permissions to create releases in the other repo
49+
# or you set the "contents" permissions to "write" as in this example
50+
changelog-path: changelog.md
51+
tag-name-prefix: ''
52+
tag-name-extension: ''
53+
release-name-prefix: ''
54+
release-name-extension: ''
55+
draft-release: true
56+
prerelease: false

‎.github/workflows/test-release.yaml‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@ name: Upload Python Package to test.pypi.org
66
on: [pull_request]
77

88
permissions:
9-
contents: read
9+
contents: write
1010

1111
jobs:
1212
test-deploy:
1313
runs-on: ubuntu-latest
1414
steps:
1515
- name: Checkout
16-
uses: actions/checkout@v2
16+
uses: actions/checkout@v3
1717
- name: Set up Python
1818
uses: actions/setup-python@v3
1919
with:
@@ -51,3 +51,16 @@ jobs:
5151
skip_existing: true
5252
verbose: true
5353
print_hash: true
54+
- name: 'Create changelog based prerelease'
55+
uses: brainelectronics/changelog-based-release@v1
56+
with:
57+
# note you'll typically need to create a personal access token
58+
# with permissions to create releases in the other repo
59+
# or you set the "contents" permissions to "write" as in this example
60+
changelog-path: changelog.md
61+
tag-name-prefix: ''
62+
tag-name-extension: '-rc${{ github.run_number }}.dev${{ github.event.number }}'
63+
release-name-prefix: ''
64+
release-name-extension: '-rc${{ github.run_number }}.dev${{ github.event.number }}'
65+
draft-release: true
66+
prerelease: true

‎README.md‎

Lines changed: 40 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -16,82 +16,64 @@ Forked from [Exo Sense Py][ref-sferalabs-exo-sense], based on
1616
[PyCom Modbus][ref-pycom-modbus] and extended with other functionalities to
1717
become a powerfull MicroPython library
1818

19-
## Installation
19+
<!-- MarkdownTOC -->
2020

21-
<!--
22-
The current implementation does only run on a board with external SPI RAM. As
23-
of now up to 300kB of RAM are required. This is more than an ESP32-D4 Pico
24-
provides by default.
21+
- [Quickstart](#quickstart)
22+
- [Install package on board with pip](#install-package-on-board-with-pip)
23+
- [Install additional MicroPython packages](#install-additional-micropython-packages)
24+
- [Usage](#usage)
25+
- [Master implementation](#master-implementation)
26+
- [Slave implementation](#slave-implementation)
27+
- [Register configuration](#register-configuration)
28+
- [Supported Modbus functions](#supported-modbus-functions)
29+
- [Credits](#credits)
2530

26-
`esp32spiram-20220117-v1.18.bin` is used as MicroPython firmware
27-
-->
31+
<!-- /MarkdownTOC -->
2832

29-
### Install required tools
33+
## Quickstart
3034

31-
Python3 must be installed on your system. Check the current Python version
32-
with the following command
35+
This is a quickstart to install the `micropython-modbus` library on a
36+
MicroPython board.
3337

34-
```bash
35-
python --version
36-
python3 --version
37-
```
38-
39-
Depending on which command `Python 3.x.y` (with x.y as some numbers) is
40-
returned, use that command to proceed.
38+
A more detailed guide of the development environment can be found in
39+
[SETUP](SETUP.md)
4140

4241
```bash
4342
python3 -m venv .venv
4443
source .venv/bin/activate
4544

46-
pip install -r requirements.txt
45+
pip install 'rshell>=0.0.30,<1.0.0'
4746
```
4847

49-
## Setup
50-
51-
### Install package with pip
52-
53-
Connect to a network
54-
55-
```python
56-
import network
57-
station = network.WLAN(network.STA_IF)
58-
station.connect('SSID', 'PASSWORD')
59-
station.isconnected()
60-
```
61-
62-
and install this lib on the MicroPython device like this
63-
64-
```python
65-
import upip
66-
upip.install('micropython-modbus')
67-
```
68-
69-
### Manually
70-
71-
#### Upload files to board
72-
73-
Copy the module to the MicroPython board and import them as shown below
74-
using [Remote MicroPython shell][ref-remote-upy-shell]
75-
76-
Open the remote shell with the following command. Additionally use `-b 115200`
77-
in case no CP210x is used but a CH34x.
48+
### Install package on board with pip
7849

7950
```bash
8051
rshell -p /dev/tty.SLAB_USBtoUART --editor nano
8152
```
8253

83-
Perform the following command to copy all files and folders to the device
54+
Inside the rshell
8455

8556
```bash
86-
mkdir /pyboard/lib
87-
mkdir /pyboard/lib/umodbus
88-
mkdir /pyboard/registers
89-
90-
cp registers/modbusRegisters-MyEVSE.json /pyboard/registers/
91-
cp umodbus/* /pyboard/lib/umodbus
92-
9357
cp main.py /pyboard
9458
cp boot.py /pyboard
59+
repl
60+
```
61+
62+
Inside the REPL
63+
64+
```python
65+
import machine
66+
import network
67+
import time
68+
import upip
69+
station = network.WLAN(network.STA_IF)
70+
station.active(True)
71+
station.connect('SSID', 'PASSWORD')
72+
time.sleep(1)
73+
print('Device connected to network: {}'.format(station.isconnected()))
74+
upip.install('micropython-modbus')
75+
print('Installation completed')
76+
machine.soft_reset()
9577
```
9678

9779
### Install additional MicroPython packages
@@ -111,6 +93,8 @@ or check the README of the
11193

11294
## Usage
11395

96+
See also [USAGE](USAGE.md)
97+
11498
Start a REPL (may perform a soft reboot), wait for network connection and
11599
start performing Modbus requests to the device.
116100

@@ -211,7 +195,7 @@ Use the provided example scripts [read RTU](examples/read_registers_rtu.sh) or
211195
[read TCP](examples/read_registers_tcp.sh) to read the data from the devices.
212196
This requires the [modules submodule][ref-github-be-python-modules] to be
213197
cloned as well and the required packages being installed as described in the
214-
modules README file.
198+
modules README file. For further details read the [SETUP](SETUP.md) guide.
215199

216200
### Register configuration
217201

‎SETUP.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Setup
2+
3+
Setup the development environment and the MicroPython board
4+
5+
---------------
6+
7+
<!-- MarkdownTOC -->
8+
9+
- [Development environment](#development-environment)
10+
- [Update submodule](#update-submodule)
11+
- [Install required tools](#install-required-tools)
12+
- [MicroPython](#micropython)
13+
- [Flash firmware](#flash-firmware)
14+
- [Install package with pip](#install-package-with-pip)
15+
- [Without network connection](#without-network-connection)
16+
17+
<!-- /MarkdownTOC -->
18+
19+
## Development environment
20+
21+
This section describes the necessary steps on the computer to get ready to
22+
test and run the examples.
23+
24+
### Update submodule
25+
26+
[brainelectronics python modules submodule][ref-github-be-python-modules] have
27+
to be cloned as well. A standard clone command won't clone the submodule.
28+
29+
```bash
30+
git submodule update --init --recursive
31+
cd modules
32+
git fetch
33+
34+
# maybe checkout a newer version with the following command
35+
git checkout x.y.z
36+
37+
# or use the latest develop branch
38+
git checkout develop
39+
git pull
40+
```
41+
42+
### Install required tools
43+
44+
Python3 must be installed on your system. Check the current Python version
45+
with the following command
46+
47+
```bash
48+
python --version
49+
python3 --version
50+
```
51+
52+
Depending on which command `Python 3.x.y` (with x.y as some numbers) is
53+
returned, use that command to proceed.
54+
55+
```bash
56+
python3 -m venv .venv
57+
source .venv/bin/activate
58+
59+
pip install -r requirements.txt
60+
pip install -r modules/requirements.txt
61+
```
62+
63+
## MicroPython
64+
65+
This section describes the necessary steps on the MicroPython device to get
66+
ready to test and run the examples.
67+
68+
### Flash firmware
69+
70+
Flash the [MicroPython firmware][ref-upy-firmware-download] to the MicroPython
71+
board with this call
72+
73+
```bash
74+
esptool.py --chip esp32 --port /dev/tty.SLAB_USBtoUART erase_flash
75+
esptool.py --chip esp32 --port /dev/tty.SLAB_USBtoUART --baud 921600 write_flash -z 0x1000 esp32spiram-20220117-v1.18.bin
76+
```
77+
78+
### Install package with pip
79+
80+
Connect to a network
81+
82+
```python
83+
import network
84+
station = network.WLAN(network.STA_IF)
85+
station.connect('SSID', 'PASSWORD')
86+
station.isconnected()
87+
```
88+
89+
and install this lib on the MicroPython device like this
90+
91+
```python
92+
import upip
93+
upip.install('micropython-modbus')
94+
```
95+
96+
### Without network connection
97+
98+
Copy the module to the MicroPython board and import them as shown below
99+
using [Remote MicroPython shell][ref-remote-upy-shell]
100+
101+
Open the remote shell with the following command. Additionally use `-b 115200`
102+
in case no CP210x is used but a CH34x.
103+
104+
```bash
105+
rshell -p /dev/tty.SLAB_USBtoUART --editor nano
106+
```
107+
108+
Perform the following command to copy all files and folders to the device
109+
110+
```bash
111+
mkdir /pyboard/lib
112+
mkdir /pyboard/lib/umodbus
113+
114+
cp umodbus/* /pyboard/lib/umodbus
115+
```
116+
117+
<!-- Links -->
118+
[ref-github-be-python-modules]: https://github.com/brainelectronics/python-modules
119+
[ref-upy-firmware-download]: https://micropython.org/download/
120+
[ref-remote-upy-shell]: https://github.com/dhylands/rshell

0 commit comments

Comments
 (0)