aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMichael Buesch <m@bues.ch>2019-06-02 19:17:51 +0200
committerMichael Buesch <m@bues.ch>2019-06-02 19:17:51 +0200
commitafb85bda17c550ab197ac1770cecaee82d399316 (patch)
tree6f112ab24ff1ef9b9485da49fe9b634dc6c177e6
parent547863f47744399706a6d43673e5f4c6e281d9a7 (diff)
downloadpyprofibus-afb85bda17c550ab197ac1770cecaee82d399316.tar.xz
pyprofibus-afb85bda17c550ab197ac1770cecaee82d399316.zip
doc: Add more hardware documentation
Signed-off-by: Michael Buesch <m@bues.ch>
-rw-r--r--README.md69
-rw-r--r--doc/hardware.md42
-rw-r--r--doc/hardware_fpga.md60
3 files changed, 163 insertions, 8 deletions
diff --git a/README.md b/README.md
index a25e1ae..332883a 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,70 @@
-pyprofibus - PROFIBUS-DP stack
-==============================
+# pyprofibus - PROFIBUS-DP stack
pyprofibus is a [PROFIBUS-DP](https://en.wikipedia.org/wiki/Profibus)
stack written in Python.
-Dependencies
-------------
-* Python 2.7 or Python 3.x: [python.org](https://www.python.org/)
+## Hardware
-License
--------
-Copyright (c) 2013-2018 Michael Buesch <m@bues.ch>
+What hardware can pyprofibus be run on? Please read the hardware documentation for more information:
+
+[pyprofibus hardware documentation](doc/hardware.html)
+
+
+## Examples
+
+pyprofibus comes with a couple of examples that can teach you how to use pyprofibus in your project.
+
+<table>
+
+<tr>
+<td>
+<pre>
+example_dummy.py
+example_dummy.conf
+</pre>
+</td>
+<td>
+Example that runs pyprofibus without any hardware.<br />
+This example can be used to play around with pyprofibus.
+</td>
+</tr>
+
+<tr>
+<td>
+<pre>
+example_et200s.py
+example_et200s.conf
+</pre>
+</td>
+<td>
+Example that runs pyprofibus as master connected to an ET&nbsp;200S as slave.
+</td>
+</tr>
+
+<tr>
+<td>
+<pre>
+example_s7-315-2dp.py
+example_s7-315-2dp.conf
+</pre>
+</td>
+<td>
+Example that runs pyprofibus as master connected to an S7-315-2DP as <u>slave</u>.
+</td>
+</tr>
+
+</table>
+
+
+## Dependencies
+
+* Python 3.4 or later or Python 2.7: [python.org](https://www.python.org/)
+
+
+## License
+
+Copyright (c) 2013-2019 Michael Buesch <m@bues.ch>
Licensed under the terms of the GNU General Public License version 2,
or (at your option) any later version.
diff --git a/doc/hardware.md b/doc/hardware.md
new file mode 100644
index 0000000..92143a4
--- /dev/null
+++ b/doc/hardware.md
@@ -0,0 +1,42 @@
+# pyprofibus hardware documentation
+
+pyprofibus can run on about anything that has a serial port.
+
+However some hardware is superior to other. See the documentation below for the various hardware alternatives and its characteristics.
+
+
+## pyprofibus on Linux with FPGA PHY
+
+This is the fastest albeit most expensive alternative to connect pyprofibus to a Profibus network. Currently bitrates of up to 1.5 MBaud are supported.
+
+The pyprofibus FPGA is connected via high speed SPI bus to the host computer. It's known to work well with the Raspberry Pi. However it's not strictly limited to that as host computer. The pyprofibus FPGA PHY driver utilizes the Linux SPI subsystem for communication to the FPGA board.
+
+Please see the
+[pyprofibus FPGA PHY documentation](hardware_fpga.html)
+for more information on how to build and run the FPGA PHY.
+
+
+## pyprofibus on Linux with /dev/ttyS0 or /dev/ttyAMA0 serial port
+
+Using the Linux serial port is a supported albeit slow alternative to connect pyprofibus to a Profibus network. It only supports low bitrates of up to about 19200 baud (depends on the actual hardware).
+
+Use the pyprofibus configuration as follows to run pyprofibus on serial port:
+
+<pre>
+[PHY]
+type=serial
+dev=/dev/ttyS0
+rtscts=False
+dsrdtr=False
+baud=19200
+</pre>
+
+
+## pyprofibus on Linux with /dev/ttyUSB0 serial port
+
+It is not recommended to run pyprofibus on an emulated USB serial adapter. USB does not meet the realtime requirements of Profibus. It might work at slow bitrates, though. Use without any guarantees.
+
+
+## pyprofibus on MS Windows
+
+pyprofibus has been reported to work on Windows with the `serial` PHY. Just use the COM1 / COM2 / COMx as `dev=` in the configuration. The same restrictions apply as with Linux `serial` PHY. Please the the Linux /dev/ttyS0 section.
diff --git a/doc/hardware_fpga.md b/doc/hardware_fpga.md
new file mode 100644
index 0000000..a00cde3
--- /dev/null
+++ b/doc/hardware_fpga.md
@@ -0,0 +1,60 @@
+# pyprofibus FPGA PHY documentation
+
+Instead of using the serial port of the host computer to connect to the Profibus network an FPGA can be used. That improves the realtime capabilities and the speed of the pyprofibus system.
+
+
+## FPGA boards
+
+Currently only the [TinyFPGA BX](https://tinyfpga.com/) is supported as FPGA.
+
+However it's possible to add support for other FPGAs.
+The TinyFPGA&nbsp;BX has been chosen, because it has a fully Open Source toolchain. So the pyprofibus FPGA Verilog sources can be translated to the binary FPGA bitstream using only freely available tools.
+
+The pyprofibus releases come with pre-built bitstream images. So there's no need for the user to install the toolchain and build the FPGA bitstream. The only tool that is needed is the "flashing/programming tool" that is used to transfer the binary bitstream to the FPGA board.
+
+
+### Flashing / Programming tool
+
+For the purpose of writing/downloading/flashing the binary FPGA bitstream to the TinyFPGA&nbsp;BX board the [tinyprog](https://github.com/tinyfpga/TinyFPGA-Bootloader/) tool can be used.
+
+The helper script `tinyfpga_bx_program.sh` shipped with pyprofibus in the subdirectory `phy_fpga/bin/tinyfpga_bx` can be used to conveniently call `tinyprog` with the correct parameters. Just connect the TinyFPGA&nbsp;BX board via USB to the computer and run the `tinyfpga_bx_program.sh` script. It does everything to program the pyprofibus PHY to your TinyFPGA&nbsp;BX.
+
+### Build toolchain
+
+If you want to modify the FPGA sources and build your own version of the FPGA bitstream, the following tools are required:
+
+
+#### Project IceStorm
+
+The [Project IceStorm](http://www.clifford.at/icestorm/) is needed to build the bitstream for the TinyFPGA&nbsp;BX board.
+
+
+#### Yosys
+
+The [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/) is required to synthesize the Verilog sources.
+
+
+#### nextpnr
+
+The [nextpnr FPGA place and route tool](https://github.com/YosysHQ/nextpnr) is required for FPGA routing.
+
+
+#### Python
+
+[Python 3.7](https://www.python.org/) or later is required to auto-generate some parts of the sources.
+
+
+#### GNU make an other standard GNU/Linux shell utilities
+
+[GNU make](https://www.gnu.org/software/make/) and various other standard GNU/Linux shell utilities, that are already installed on any Desktop Linux distribution. Building on Windows is not supported.
+
+
+### Building pyprofibus PHY-FPGA
+
+To build the PHY-FPGA sources run the following commands:
+
+<pre>
+cd phy_fpga
+make clean
+make
+</pre>
bues.ch cgit interface