From 113ec3bc0efd2c411ccd433af491e57bbf40ff42 Mon Sep 17 00:00:00 2001
From: Fredrik Bagge Carlson <cont-frb@ulund.org>
Date: Sun, 20 Aug 2017 22:32:07 +0200
Subject: [PATCH] Update readme
---
README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++-
src/interface.jl | 1 +
2 files changed, 62 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 1c9641c..96ed335 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,63 @@
# LabProcesses
+This package contains an (programming- as well as connection-) interface to serve
+as a base for the implementation of lab-process software. The first exampel of
+an implementaiton of this interface is for the ball-and-beam process, which is
+used in Lab1 FRTN35: frequency response analysis of the beam. The lab is implemented
+in [BallAndBeam.jl](https://gitlab.control.lth.se/processes/BallAndBeam.jl), a
+package that makes use of `LabProcesses.jl` to handle the communication with
+the lab process and/or a simulated version thereof. This way, the code written
+for frequency response analysis of the beam can be run on another process
+implementing the same interface (or a simulated version) by changeing a single
+line of code :)
-Under development /Bagge
+## Installation
+1. Start julia
+2. Install LabProcesses.jl using command Pkg.clone("https://gitlab.control.lth.se/processes/LabProcesses.jl.git") Lots of packages will now be installed, this will take some time.
+
+## How to implement a new process
+1. Locate the file [interface.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface.jl)
+2. Copy all function definitions.
+3. Create a new file under `/interface_implementations` where you paste all the
+copied definitions and implement them. See [`/interface_implementations/ballandbeam.jl`](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_implementations/ballandbeam.jl) for an example.
+4. Above all function implementations you must define the process type, e.g,
+```julia
+struct BallAndBeam <: PhysicalProcess
+ h::Float64
+end
+BallAndBeam() = BallAndBeam(0.01) # Constructor with default value of sample time
+```
+Make sure you inherit from `PhysicalProcess` or `SimulatedProcess` as appropriate.
+5. Documentation of all interface functions is available in the file [interface_documentation.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_documentation.jl)
+
+## Control a process
+The interface `AbstractProcess` defines the functions `control(P, u)` and `measure(P)`.
+These functions can be used to implement your own control loops. A common loop
+with a feedback controller and a feedforward filter on the reference is implemented
+in the function [`run_control_2DOF`](@ref).
+
+The macro `@periodically` might come in handy if you want to implement your own loop.
+Consider the following example, in which the loop body will be run periodically
+with a sample time of `h` seconds.
+```julia
+for (i,t) = enumerate(0:h:duration)
+ @periodically h begin
+ y[i] = measure(P)
+ r[i] = reference(t)
+ u[i] = control(i)
+ control(P, u[i])
+ end
+end
+```
+
+Often one finds the need to implement a stateful controller, i.e., a function
+that has a memory or state. To this end, the function [`sysfilter`](@ref) is
+provided. Usage is demonstrated below
+```julia
+stateC = init_sysfilter(C)
+function control(i)
+ e = r[i]-y[i]
+ ui = sysfilter!(stateC, C, e)
+end
+```
+`C` must here be represented by a [`StateSpace`](@ref) type from [`ControlSystems.jl`](https://github.com/JuliaControl/ControlSystems.jl).
+`TransferFunction` types can easily be converted to a `StateSpace` by `Gss = ss(Gtf)`.
diff --git a/src/interface.jl b/src/interface.jl
index bff7bd9..065dbd6 100644
--- a/src/interface.jl
+++ b/src/interface.jl
@@ -16,6 +16,7 @@ abstract type AbstractProcess end
abstract type PhysicalProcess <: AbstractProcess end
abstract type SimulatedProcess <: AbstractProcess end
+## Function definitions =====================================================================
num_outputs(p::AbstractProcess) = error("Function not implemented for $(typeof(p))")
num_inputs(p::AbstractProcess) = error("Function not implemented for $(typeof(p))")
outputrange(p::AbstractProcess) = error("Function not implemented for $(typeof(p))")
--
GitLab