Merge branch 'master' of gitlab.control.lth.se:labdev/LabConnections.jl

README.md

 [![pipeline status](https://gitlab.control.lth.se/labdev/LabConnections.jl/badges/master/pipeline.svg)](https://gitlab.control.lth.se/labdev/LabConnections.jl/commits/master)
 [![coverage report](https://gitlab.control.lth.se/labdev/LabConnections.jl/badges/master/coverage.svg)](https://gitlab.control.lth.se/labdev/LabConnections.jl/commits/master)
 
-Documentation available at [Documentation](https://gitlab.control.lth.se/labdev/LabConnections.jl/blob/master/docs/build/index.html)
+# Welcome to LabConnections.jl - the IO-software part of the LabDev project
 
-# OBS! SPI development
-The SPI development is done in C and in a forked repository, currently
-separated from the julia project. If you wish to work on the SPI implementation,
-simply clone the repository "serbus", a small C stack available at
-`github.com/mgreiff/serbus` into your julia package directory (for example
-`~/.julia/v0.6`). Then, in the LabConnections package on the host computer, run
-`flash_BB.sh` in the `/utils` directory transferring both LabConnections and
-serbus to the BB.
+The goal of this project is to develop a software package in [Julia](https://julialang.org/) 
+for interfacing with lab processes using either the [BeagleBone Black Rev C](http://beagleboard.org/) (BBB)
+with custom [IO-board cape](https://gitlab.control.lth.se/labdev/ioboards), or the old IO-boxes in the labs using Comedi.
+With this package, the user is able to setup a connection between the 
+host computer and the IO-device, and send and 
+receive control signals and measurements from the lab process.
 
-On the BB, run
+The full documentation of the package is available [here](https://gitlab.control.lth.se/labdev/LabConnections.jl/blob/master/docs/build/index.md).
 
-    cp /home/debian/juliapackages/serbus/bb_spi.sh /home/debian
+## Package Overview
+The `LabConnections.jl` package is subdivided into two main modules; `Computer.jl` 
+and `BeagleBone.jl`. `Computer.jl` defines the user interface on the host
+computer side, while `BeagleBone.jl` defines low-level types and functions meant
+to be used locally on the BBB.
 
-and then execute
+### BeagleBone.jl
+This module defines types representing different pins and LEDs on the BBB, and
+functions to change their status and behaviour. There are currently 4 different types defined
+(each has the abstract super type `IO_Object`):
+* `GPIO` : Represents the BBB's General Purpose Input Output (GPIO) pins. 
+Each instance will correspond to a physical GPIO pin on the board, and can be 
+set as an input or output pin, and to output high (1) or low (0).
+* `PWM` : Represents the BBB's Pulse Width Modulation (PWM) pins. 
+Each instance will correspond to a physical PWM pin on the board, which can be
+turned on/off, and whose period, duty cycle and polarity can be specified.
+* `SysLED` : Represents the 4 system LEDs on the BBB, and can be turned on/off.
+Used to perform simple tests and debugging on the BBB.
+* `Debug` : Used for debugging and pre-compilation on the BBB. It does 
+not represent any physical pin or LED on the board.
+
+**Note:** In addition to GPIO and PWM, the BBB also has pins dedicated for [Serial Peripheral
+Interface](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus) (SPI).
+Work to feature this functionality in `BeagleBone.jl` is currently ongoing. More
+information can be found [here](https://gitlab.control.lth.se/labdev/LabConnections.jl/blob/master/docs/build/man/introduction.md#spi-development)
+
+
+### Computer.jl
+This module contains the user interface on the host computer side, and defines 
+types for devices/connections to the lab process, and filestreams between the 
+host computer and different IO-devices (BBB or Comedi). There are currently 3 
+different device/connection types (each has the abstract super type `AbstractDevice`):
+* `AnalogInput10V` : Represents ±10V connections from the lab process to the IO-device. Each instance will correspond to a physical ±10V measurement signal from the lab process, whose value can be read.
+* `AnalogOutput10V` : Represents ±10V connections from the IO-device to the lab process. Each instance will correspond to a physical ±10V input signal to the lab process, whose value can be set.  
+* `SysLED` : Represents the System LEDs on the BBB. Used for simple testing and debugging from the host computer side.
+
+There are 2 different filestream types (each has the abstract super type `LabStream`):
+* `BeagleBoneStream` : Represents the data stream between the host computer and the BBB.
+* `ComediStream` : Represent the data stream between the host computer and the old IO-boxes using Comedi. 
+
+## Getting Started
+Instructions on installing the required software and setting up a connection between 
+the host computer and the BBB are found [here](https://gitlab.control.lth.se/labdev/LabConnections.jl/blob/master/docs/build/man/installation.md#installation-instructions)
+
+After successfully setting up a connection between host computer and BBB, there
+are several examples found [here](https://gitlab.control.lth.se/labdev/LabConnections.jl/blob/master/docs/build/examples/examples.md#examples)
+which let's you test out the functionality of `LabConnections.jl`.
 
-    ./bb_spi.sh
 
-in the `/home/debian` directory to run the SPI example with the ADC from SPI0.

docs/build/index.md

@@ -43,8 +43,8 @@
 - [`Base.read`](lib/functions.md#Base.read)
 - [`Base.read`](lib/functions.md#Base.read)
 - [`LabConnections.BeagleBone.assert_pwm_write`](lib/functions.md#LabConnections.BeagleBone.assert_pwm_write-Tuple{Int32,String})
-- [`LabConnections.BeagleBone.bbparse`](lib/functions.md#LabConnections.BeagleBone.bbparse-Tuple{Tuple,Any})
 - [`LabConnections.BeagleBone.bbparse`](lib/functions.md#LabConnections.BeagleBone.bbparse-Tuple{Any})
+- [`LabConnections.BeagleBone.bbparse`](lib/functions.md#LabConnections.BeagleBone.bbparse-Tuple{Tuple,Any})
 - [`LabConnections.BeagleBone.closedev`](lib/functions.md#LabConnections.BeagleBone.closedev-Tuple{String,Int32})
 - [`LabConnections.BeagleBone.export_gpio`](lib/functions.md#LabConnections.BeagleBone.export_gpio-Tuple{Int32})
 - [`LabConnections.BeagleBone.export_led`](lib/functions.md#LabConnections.BeagleBone.export_led)

docs/build/lib/io_devices.md

@@ -15,25 +15,33 @@
 
 
 ```
-Debug()
+Debug(i::Int32)
 ```
 
-Type for debugging and precompile
+Type for debugging and precompile.
 
 <a id='LabConnections.BeagleBone.GPIO' href='#LabConnections.BeagleBone.GPIO'>#</a>
 **`LabConnections.BeagleBone.GPIO`** &mdash; *Type*.
 
 
 
-Lowest form of communication with the GPIO pins. The available pins are listed in the "channel" parameter, and appear as directories in /sys/class/gpio after being exported.
+```
+GPIO(i::Int32)
+```
 
-For instance, to setup a GPIO on "gpio112", configure it as an output pin and set it to high, the following code would be used.
+Lowest form of communication with the GPIO pins. The available pins are listed in the "channel" parameter, and appear as directories in /sys/class/gpio after being exported. For instance, to setup a GPIO on "gpio112", configure it as an output pin and set it to high, the following code would be used.
 
-gpio = GPIO(1)   write!(gpio, (2,"out"))   write!(gpio, (1, "1"))
+```
+`gpio = GPIO(1)`
+`write!(gpio, (2,"out"))`
+`write!(gpio, (1, "1"))`
+```
 
 The operation of reading the current output value of the GPIO is done by
 
-read(gpio, 1)
+```
+`read(gpio, 1)`
+```
 
 See the test/BeagleBone/GPIO_test.jl for more examples.
 
@@ -49,19 +57,19 @@ Define abstract type for pins/LEDS on the BeagleBone
 
 
 
-This script allows for low level PWM control of selected pins The valid pins dictionary relates to memory adresses in of the AM3359 chip, see p.182 in
-
 ```
-www.ti.com/product/AM3359/technicaldocuments
+PWM(i::Int32)
 ```
 
+This device allows for low level PWM control of selected pins. The valid pins dictionary pwm_pins relates to memory adresses in of the AM3359 chip, see p.182 in www.ti.com/product/AM3359/technicaldocuments.
+
 <a id='LabConnections.BeagleBone.SysLED' href='#LabConnections.BeagleBone.SysLED'>#</a>
 **`LabConnections.BeagleBone.SysLED`** &mdash; *Type*.
 
 
 
 ```
-SysLED
+SysLED(i::Int32)
 ```
 
 Type representing the system LEDs on the BeagleBone. The LEDs are indexed by i ∈ [1,2,3,4].

docs/build/man/introduction.md

-
 <a id='Introduction-1'></a>
 
 # Introduction
@@ -8,3 +7,24 @@
 
 ## Installation
 
+## Future Work
+
+### SPI Development
+The SPI development is done in C and in a forked repository, currently
+separated from the julia project. If you wish to work on the SPI implementation,
+simply clone the repository "serbus", a small C stack available at
+`github.com/mgreiff/serbus` into your julia package directory (for example
+`~/.julia/v0.6`). Then, in the LabConnections package on the host computer, run
+`flash_BB.sh` in the `/utils` directory transferring both LabConnections and
+serbus to the BB.
+
+On the BB, run
+
+    cp /home/debian/juliapackages/serbus/bb_spi.sh /home/debian
+
+and then execute
+
+    ./bb_spi.sh
+
+in the `/home/debian` directory to run the SPI example with the ADC from SPI0.
+

src/BeagleBone/BeagleBone.jl

@@ -11,10 +11,12 @@ const DEVICES = Dict("debug" => Debug, "sysled" => SysLED, "gpio" => GPIO, "pwm"
 active_devices = Dict{String,Dict{Int32,IO_Object}}("debug" => Dict{Int32,Debug}(), "sysled" => Dict{Int32,SysLED}(),
                                                           "gpio" => Dict{Int32,GPIO}(), "pwm" => Dict{Int32,PWM}())
 
-@doc """ active_device = initdev(dev_name::String, i:Int32)
+"""
+    active_device = initdev(dev_name::String, i:Int32)
 Initializes a new device of type 'dev_name' at index 'i' on the BeagleBone,
 and adds it to the dict of currently active devices. Returns the initialized
-device 'active_device'."""->
+device 'active_device'.
+"""
 function initdev(dev_name::String, i::Int32)
     #Check if the type of device is valid
     dev_constr = try
@@ -30,10 +32,11 @@ function initdev(dev_name::String, i::Int32)
     return active_device
 end
 
-@doc """ closedev(dev_name::String, i::Int32)
+"""
+    closedev(dev_name::String, i::Int32)
 Closes down a currently active device of type 'dev_name' at index 'i' on the BeagleBone,
 and removes it from the dict of currently active devices.
-""" ->
+"""
 function closedev(dev_name::String, i::Int32)
     active_device = try
         active_devices[dev_name][i]
@@ -50,7 +53,7 @@ end
 
 """
     dev = getdev(dev_name::String, i::Int32)
-Retrieves the active device of type `dev_name` at index 'i'
+Retrieves the active device of type `dev_name` at index 'i'.
 """
 function getdev(dev_name::String, i::Int32)
     dev = try
@@ -63,8 +66,8 @@ end
 
 """
     message = listdev()
-Lists all the active devices as an insidence array for testing
-"""
+Lists all the active devices as an insidence array for testing.
+    """
 function listdev()
     message = "Complete overview of active devices"
     count = zeros(length(keys(DEVICES)))
@@ -76,7 +79,7 @@ end
 
 """
     message = printdev()
-Prints all the active devices and writes out specifics of a single devices
+Prints all the active devices and writes out specifics of a single devices.
 """
 function printdev(dev_name::String, i::Int32)
     println("Complete overview of active devices")
@@ -93,11 +96,10 @@ end
 
 """
     bbparse(cmd)
-Parse and execute the command `cmd`
+Parse and execute the command `cmd`.
 """
 bbparse(any) = error("Unexpected input: $any")
 
-
 function bbsend(sock, vals)#, timestamps)
     serialize(sock, vals)#, (timestamps...)))
 end
@@ -109,8 +111,7 @@ where if `iswrite`
     `cmdi = (devname, id, val)`
     and if not `iswrite`
     `cmdi = (devname, id)`
-
-and send back on socket (vals, timestamps)
+and send back on socket (vals, timestamps).
 """
 function bbparse(l::Tuple, sock)
     iswrite = l[1]::Bool            #True if write command, false if read
@@ -141,7 +142,7 @@ global __waiting_first_connection__ = false
 """
     run_server(port=2001; debug=false)
 Run a server on `port` that listens for commands from computer
-Optional debug keyword disables blinking system leds
+Optional debug keyword disables blinking system leds.
 """
 function run_server(port=2001; debug=false)
     global __waiting_first_connection__ = true

src/BeagleBone/Debug.jl

 """
-    Debug()
-Type for debugging and precompile
+    Debug(i::Int32)
+Type for debugging and precompile.
 """
 type Debug <: IO_Object
     i::Int32

src/BeagleBone/GPIO.jl

 """
+    GPIO(i::Int32)
 Lowest form of communication with the GPIO pins. The available pins are
 listed in the "channel" parameter, and appear as directories in /sys/class/gpio
-after being exported.
-
-For instance, to setup a GPIO on "gpio112", configure it as an output pin and set
+after being exported. For instance, to setup a GPIO on "gpio112", configure it as an output pin and set
 it to high, the following code would be used.
 
-  gpio = GPIO(1)
-  write!(gpio, (2,"out"))
-  write!(gpio, (1, "1"))
+    `gpio = GPIO(1)`
+    `write!(gpio, (2,"out"))`
+    `write!(gpio, (1, "1"))`
 
 The operation of reading the current output value of the GPIO is done by
 
-  read(gpio, 1)
+    `read(gpio, 1)`
 
 See the test/BeagleBone/GPIO_test.jl for more examples.
 """
@@ -37,7 +36,7 @@ type GPIO <: IO_Object
 end
 
 """
-  write!(gpio::GPIO, args::Tuple{Int32,String}, debug::Bool=false)
+    write!(gpio::GPIO, args::Tuple{Int32,String}, debug::Bool=false)
 Writes an entry to an operation on a GPIO, of the form args = (operation, entry).
 """
 function write!(gpio::GPIO, args::Tuple{Int32,String}, debug::Bool=false)
@@ -55,7 +54,7 @@ function write!(gpio::GPIO, args::Tuple{Int32,String}, debug::Bool=false)
 end
 
 """
-  l = read(gpio::GPIO, operation::Int32, debug::Bool=false)
+    l = read(gpio::GPIO, operation::Int32, debug::Bool=false)
 Reads the current value from an operation on a GPIO.
 """
 function read(gpio::GPIO, operation::Int32, debug::Bool=false)
@@ -67,9 +66,10 @@ function read(gpio::GPIO, operation::Int32, debug::Bool=false)
   return l
 end
 
-@doc """ teardown(gpio::GPIO, debug::Bool=false)
+"""
+    teardown(gpio::GPIO, debug::Bool=false)
 Closes all open streams on the GPIO, and unexports it from the file system.
-""" ->
+"""
 function teardown(gpio::GPIO, debug::Bool=false)
   debug && return
 
@@ -96,7 +96,7 @@ function teardown(gpio::GPIO, debug::Bool=false)
 end
 
 """
-  export_gpio(i::Int32, debug::Bool=false)
+    export_gpio(i::Int32, debug::Bool=false)
 Export the GPIO file system, either for real-time or testing usecases.
 """
 function export_gpio(i::Int32)
@@ -124,7 +124,8 @@ function export_gpio(i::Int32)
 end
 
 """
-  to_string(gpio::GPIO, debug::Bool=false)
+    to_string(gpio::GPIO, debug::Bool=false)
+
 Generates a string representation of the GPIO device.
 """
 function to_string(gpio::GPIO, debug::Bool=false)

src/BeagleBone/IO_Object.jl

@@ -3,9 +3,6 @@ Define abstract type for pins/LEDS on the BeagleBone
 """
 abstract type IO_Object end
 
-"""
-GPIO interfaces
-"""
 const gpio_operations = [
   ["1", "0"],
   ["in", "out"],

src/BeagleBone/PWM.jl

 """
-This script allows for low level PWM control of selected pins
-The valid pins dictionary relates to memory adresses in of the
-AM3359 chip, see p.182 in
-
-    www.ti.com/product/AM3359/technicaldocuments
+    PWM(i::Int32)
+This device allows for low level PWM control of selected pins. The valid pins
+dictionary pwm_pins relates to memory adresses in of the AM3359 chip, see p.182
+in www.ti.com/product/AM3359/technicaldocuments.
 """
 
 type PWM <: IO_Object
@@ -53,7 +52,7 @@ end
 
 """
     assert_pwm_write(operation::Int32, entry::String)
-Assertsion for the PWM input data
+Assertsion for the PWM input data.
 """
 function assert_pwm_write(operation::Int32, entry::String)
   if operation == "1"
@@ -69,7 +68,7 @@ function assert_pwm_write(operation::Int32, entry::String)
 end
 
 """
-  l = read(pwm::PWM, operation::Int32, debug::Bool=false)
+    l = read(pwm::PWM, operation::Int32, debug::Bool=false)
 Reads the current value from an operation on a GPIO.
 """
 function read(pwm::PWM, operation::Int32, debug::Bool=false)
@@ -112,7 +111,7 @@ function teardown(pwm::PWM, debug::Bool=false)
 end
 
 """
-  export_gpio(i::Int32, debug::Bool=false)
+    export_gpio(i::Int32, debug::Bool=false)
 Export the GPIO file system, either for real-time or testing usecases.
 """
 function export_pwm(i::Int32)
@@ -153,7 +152,7 @@ function export_pwm(i::Int32)
 end
 
 """
-  to_string(pwm::PWM,, debug::Bool=false)
+    to_string(pwm::PWM,, debug::Bool=false)
 Generates a string representation of the GPIO device.
 """
 function to_string(pwm::PWM, debug::Bool=false)

src/BeagleBone/SysLED.jl

 """
-    SysLED
+    SysLED(i::Int32)
 Type representing the system LEDs on the BeagleBone. The LEDs are indexed by
 i ∈ [1,2,3,4].
 """
@@ -88,7 +88,7 @@ function export_led(i::Int32, debug::Bool=false)
 end
 
 """
-  to_string(led::SysLED, debug::Bool=false)
+    to_string(led::SysLED, debug::Bool=false)
 Generates a string representation of the GPIO device.
 """
 function to_string(led::SysLED, debug::Bool=false)