From a367636aeb04d5f427b5fdf5a4ba7f5236d6b531 Mon Sep 17 00:00:00 2001
From: mgreiff <marcusgreiff.93@hotmail.com>
Date: Tue, 16 Apr 2019 10:06:04 +0200
Subject: [PATCH] Add notes on the new kernel

---
 docs/build/index.md            |   2 +-
 docs/build/lib/functions.md    |  28 ++---
 docs/build/man/development.md  | 218 ++++++++++++++++++++++++++++++++-
 docs/build/man/installation.md |   2 +-
 docs/src/man/development.md    | 133 ++++++++++++++++++++
 5 files changed, 366 insertions(+), 17 deletions(-)

diff --git a/docs/build/index.md b/docs/build/index.md
index b209639..a076763 100644
--- a/docs/build/index.md
+++ b/docs/build/index.md
@@ -49,8 +49,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{Any})
 - [`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.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)
diff --git a/docs/build/lib/functions.md b/docs/build/lib/functions.md
index 23f8f58..6f71a12 100644
--- a/docs/build/lib/functions.md
+++ b/docs/build/lib/functions.md
@@ -2,8 +2,8 @@
 - [`Base.read`](functions.md#Base.read)
 - [`Base.read`](functions.md#Base.read)
 - [`LabConnections.BeagleBone.assert_pwm_write`](functions.md#LabConnections.BeagleBone.assert_pwm_write-Tuple{Int32,String})
-- [`LabConnections.BeagleBone.bbparse`](functions.md#LabConnections.BeagleBone.bbparse-Tuple{Any})
 - [`LabConnections.BeagleBone.bbparse`](functions.md#LabConnections.BeagleBone.bbparse-Tuple{Tuple,Any})
+- [`LabConnections.BeagleBone.bbparse`](functions.md#LabConnections.BeagleBone.bbparse-Tuple{Any})
 - [`LabConnections.BeagleBone.closedev`](functions.md#LabConnections.BeagleBone.closedev-Tuple{String,Int32})
 - [`LabConnections.BeagleBone.export_gpio`](functions.md#LabConnections.BeagleBone.export_gpio-Tuple{Int32})
 - [`LabConnections.BeagleBone.export_led`](functions.md#LabConnections.BeagleBone.export_led)
@@ -45,10 +45,10 @@ Run a server on `port` that listens for commands from computer Optional debug ke
 
 
 ```julia
-l = read(pwm::PWM, operation::Int32, debug::Bool=false)
+l = read(led::SysLED, debug::Bool=false)
 ```
 
-Reads the current value from an operation on a GPIO.
+Reads the current brightness value from the LED 'SysLED'.
 
 <a id='Base.read' href='#Base.read'>#</a>
 **`Base.read`** &mdash; *Function*.
@@ -56,10 +56,10 @@ Reads the current value from an operation on a GPIO.
 
 
 ```julia
-l = read(led::SysLED, debug::Bool=false)
+l = read(pwm::PWM, operation::Int32, debug::Bool=false)
 ```
 
-Reads the current brightness value from the LED 'SysLED'.
+Reads the current value from an operation on a PWM pin.
 
 <a id='Base.read' href='#Base.read'>#</a>
 **`Base.read`** &mdash; *Function*.
@@ -144,10 +144,10 @@ Exports a dummy filesystem for testing the LED implementation
 
 
 ```julia
-export_gpio(i::Int32, debug::Bool=false)
+export_pwm(i::Int32, debug::Bool=false)
 ```
 
-Export the GPIO file system, either for real-time or testing usecases.
+Export the PWM file system, either for real-time or testing usecases.
 
 <a id='LabConnections.BeagleBone.getdev-Tuple{String,Int32}' href='#LabConnections.BeagleBone.getdev-Tuple{String,Int32}'>#</a>
 **`LabConnections.BeagleBone.getdev`** &mdash; *Method*.
@@ -199,10 +199,10 @@ Prints all the active devices and writes out specifics of a single devices.
 
 
 ```julia
-teardown(gpio::GPIO, debug::Bool=false)
+teardown(led::SysLED, debug::Bool=false)
 ```
 
-Closes all open streams on the GPIO, and unexports it from the file system.
+Closes all open filestreams for the SysLED 'led'.
 
 <a id='LabConnections.BeagleBone.teardown' href='#LabConnections.BeagleBone.teardown'>#</a>
 **`LabConnections.BeagleBone.teardown`** &mdash; *Function*.
@@ -210,10 +210,10 @@ Closes all open streams on the GPIO, and unexports it from the file system.
 
 
 ```julia
-teardown(led::SysLED, debug::Bool=false)
+teardown(gpio::GPIO, debug::Bool=false)
 ```
 
-Closes all open filestreams for the SysLED 'led'.
+Closes all open streams on the GPIO, and unexports it from the file system.
 
 <a id='LabConnections.BeagleBone.teardown' href='#LabConnections.BeagleBone.teardown'>#</a>
 **`LabConnections.BeagleBone.teardown`** &mdash; *Function*.
@@ -232,7 +232,7 @@ Closes all open streams on the PWM, and unexports it from the file system
 
 
 ```julia
-to_string(gpio::GPIO, debug::Bool=false)
+to_string(led::SysLED, debug::Bool=false)
 ```
 
 Generates a string representation of the GPIO device.
@@ -243,7 +243,7 @@ Generates a string representation of the GPIO device.
 
 
 ```julia
-to_string(led::SysLED, debug::Bool=false)
+to_string(gpio::GPIO, debug::Bool=false)
 ```
 
 Generates a string representation of the GPIO device.
@@ -257,7 +257,7 @@ Generates a string representation of the GPIO device.
 to_string(pwm::PWM,, debug::Bool=false)
 ```
 
-Generates a string representation of the GPIO device.
+Generates a string representation of the PWM pin.
 
 <a id='LabConnections.BeagleBone.write!' href='#LabConnections.BeagleBone.write!'>#</a>
 **`LabConnections.BeagleBone.write!`** &mdash; *Function*.
diff --git a/docs/build/man/development.md b/docs/build/man/development.md
index c0f9e58..9394339 100644
--- a/docs/build/man/development.md
+++ b/docs/build/man/development.md
@@ -1,3 +1,4 @@
+
 <a id='Package-Development-1'></a>
 
 # Package Development
@@ -57,7 +58,222 @@ This will transfer the current development version of `LabConnections.jl` found
 
 When testing `LabConnections.jl` with hardware in the loop, the external hardware will be connected to the pin headers on the BB. For reference, the pin map of the BeagleBone (BB) is shown below.
 
-<img src="../fig/beaglebone_black_pinmap.png">
+
+<p align="center"> <img src="../fig/beaglebone*black*pinmap.png" height="500" width="900"> </p>
+
 
 When running examples and tests with hardware in the loop, take caution not to short the BB ground with any output pin, as this will damage the board. For instance, if connecting a diode to the output pins, always use a resistor of >1 kOhm in parallel.
 
+
+<a id='Notes-on-updates-with-the-v.4.14-kernel-1'></a>
+
+## Notes on updates with the >=v.4.14 kernel
+
+
+At the time of writing, the image used to flash the beaglebone is a v4.14 kernel, more specifically Linux beaglebone 4.14.71-ti-r80.
+
+
+Since the deployment of the v4.14 kernel, the slots file and bone_capemgr have been permanantly disabled. This means that there is no need for compiling the device tree overlays as we did for the v0.6 version of the software stack. Instead, we need to configure the /boot/uEnv.txt file to enable the PWM pins correctly. Simply open the `/boot/uEnv.txt` file, add the line
+
+
+```
+cape_enable=bone_capemgr.enable_partno=univ-all,BB-ADC,BB-PWM0,BB-PWM1,BB-PWM2
+```
+
+
+and uncomment the line
+
+
+```
+disable_uboot_overlay_video=1
+```
+
+
+Reboot the BeagleBone, and you should now have access to the PWM pins.
+
+
+<a id='Changes-to-the-device-maps-1'></a>
+
+### Changes to the device maps
+
+
+The filesystem has also changed with 4.14. we now have a pwm device in `/sys/class/pwm` where we can export and then write to the PWM pins of of the BBB. However, in order to do this, we first need to idetify which pwm chip that corresponds to which pin.
+
+
+The address of each PWM interface is
+
+
+```
+> ls -lh /sys/class/pwm
+
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip0 -> ../../devices/platform/ocp/48300000.epwmss/48300100.ecap/pwm/pwmchip0
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip1 -> ../../devices/platform/ocp/48300000.epwmss/48300200.pwm/pwm/pwmchip1
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip3 -> ../../devices/platform/ocp/48302000.epwmss/48302100.ecap/pwm/pwmchip3
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip4 -> ../../devices/platform/ocp/48302000.epwmss/48302200.pwm/pwm/pwmchip4
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip6 -> ../../devices/platform/ocp/48304000.epwmss/48304100.ecap/pwm/pwmchip6
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip7 -> ../../devices/platform/ocp/48304000.epwmss/48304200.pwm/pwm/pwmchip7
+```
+
+
+Page 184 of the TI AM335x and AMIC110 Sitara Processors Technical Reference Manual gives the memory map for the PWM chips
+
+
+```
+    PWM Subsystem 0: 0x48300000
+        eCAP0: 0x48300100
+        ePWM0: 0x48300200
+    PWM Subsystem 1: 0x48302000
+        eCAP1: 0x48302100
+        ePWM1: 0x48302200
+    PWM Subsystem 2: 0x48304000
+        eCAP2: 0x48304100
+        ePWM2: 0x48304200
+```
+
+
+From this we can conclude that
+
+
+```
+ECAP0   (eCAP0) is pwmchip0
+EHRPWM0 (ePWM0) is pwmchip1
+eCAP1   (eCAP1) is pwmchip3
+EHRPWM1 (ePWM1) is pwmchip4
+eCAP2   (eCAP2) is pwmchip6
+EHRPWM2 (ePWM2) is pwmchip7
+```
+
+
+Based on the headers on the BeagleBone expansion cape
+
+
+```
+EHRPWM0A = P9_22
+EHRPWM0B = P9_21
+EHRPWM1A = P9_14
+EHRPWM1B = P9_16
+EHRPWM2A = P8_19
+EHRPWM2B = P8_13
+ECAP0    = P9_42
+```
+
+
+which means that we get a mapping
+
+
+```
+const pwm_pins = Dict(
+    "P9.22" => ("PWM0A", "pwmchip1", "0"),
+    "P9.21" => ("PWM0B", "pwmchip1", "1"),
+    "P9.14" => ("PWM1A", "pwmchip4", "0"),
+    "P9.16" => ("PWM1B", "pwmchip4", "1"),
+    "P8.19" => ("PWM2A", "pwmchip7", "0"),
+    "P8.13" => ("PWM2B", "pwmchip7", "1"),
+)
+```
+
+
+note that before the v4.14 kernel, this mapping was
+
+
+```
+const pwm_pins = Dict(
+    "P9.22" => ("PWM0A", "pwmchip0", "0"),
+    "P9.21" => ("PWM0B", "pwmchip0", "1"),
+    "P9.14" => ("PWM1A", "pwmchip2", "0"),
+    "P9.16" => ("PWM1B", "pwmchip2", "1"),
+    "P8.19" => ("PWM2A", "pwmchip4", "0"),
+    "P8.13" => ("PWM2B", "pwmchip4", "1"),
+)
+```
+
+
+<a id='Changes-to-the-file-system-1'></a>
+
+### Changes to the file system
+
+
+Before the v4.14 kernel, the file system was structured in such a way that, after export, P9.22 could be enabled by writing to the file 
+
+
+```
+/sys/class/pwm/pwmchip0/pwm0/enable
+```
+
+
+however, in the new kernel
+
+
+```
+/sys/class/pwm/pwmchip1/pwm-1:0/enable
+```
+
+
+is used to enable the PWM on the P9.22 pin.
+
+
+<a id='Testing-the-PWM-pins-individually-1'></a>
+
+### Testing the PWM pins individually
+
+
+In order to test the PWM pins from the terminal, make sure that you have added the lines in the /boot/uEnv.txt file, and then configure the desired pin to a PWM pin. For instance, if we wish to control the P9.22 pin, run
+
+
+```
+config-pin P9.22 pwm
+```
+
+
+and make sure that it is configured correctly by running
+
+
+```
+config-pin -q P9.22
+```
+
+
+which should return "P9_22 Mode: pwm". Now you first need to export the correct pin, which, according the the device mapping above, can be done by
+
+
+```
+echo 0 > /sys/class/pwm/pwmchip1/export
+```
+
+
+once this is done, we set a period and duty cycle to the pin
+
+
+```
+echo 1000000000 > /sys/class/pwm/pwmchip1/pwm-1\:0/period
+echo 800000000 > /sys/class/pwm/pwmchip1/pwm-1\:0/duty_cycle
+```
+
+
+and enable it through
+
+
+```
+echo 1 > /sys/class/pwm/pwmchip1/pwm-1\:0/enable
+```
+
+
+disable and unexport the PWM pin by
+
+
+```
+echo 0 > /sys/class/pwm/pwmchip1/pwm-1\:0/enable
+echo 0 > /sys/class/pwm/pwmchip1/unexport
+```
+
+
+Alternatively, this can be done using the Julia, by writing
+
+
+```
+p = PWM(1)
+write!(p, (1, "1"))
+write!(p, (2, "1000000000"))
+write!(p, (3, "800000000"))
+```
+
diff --git a/docs/build/man/installation.md b/docs/build/man/installation.md
index c33a812..0858bac 100644
--- a/docs/build/man/installation.md
+++ b/docs/build/man/installation.md
@@ -62,7 +62,7 @@ Start by downloading the Debian image [here](http://beagleboard.org/latest-image
 
 
 ```
-mv /home/debian/julia-<distro specific tag>/bin/julia /home/debian/julia/bin/julia
+mv /home/debian/julia-<distro specific tag> /home/debian/julia
 ```
 
 
diff --git a/docs/src/man/development.md b/docs/src/man/development.md
index 039132b..9837dfb 100644
--- a/docs/src/man/development.md
+++ b/docs/src/man/development.md
@@ -31,3 +31,136 @@ When testing `LabConnections.jl` with hardware in the loop, the external hardwar
 </p>
 
 When running examples and tests with hardware in the loop, take caution not to short the BB ground with any output pin, as this will damage the board. For instance, if connecting a diode to the output pins, always use a resistor of >1 kOhm in parallel.
+
+## Notes on updates with the >=v.4.14 kernel
+At the time of writing, the image used to flash the beaglebone is
+a v4.14 kernel, more specifically Linux beaglebone 4.14.71-ti-r80.
+
+Since the deployment of the v4.14 kernel, the slots file and bone_capemgr have been permanantly disabled. This means that there is no need for compiling the device tree overlays as we did for the v0.6 version of the software stack. Instead, we need to configure the /boot/uEnv.txt file to enable the PWM pins correctly. Simply open the `/boot/uEnv.txt` file, add the line
+
+```
+cape_enable=bone_capemgr.enable_partno=univ-all,BB-ADC,BB-PWM0,BB-PWM1,BB-PWM2
+```
+and uncomment the line
+```
+disable_uboot_overlay_video=1
+```
+Reboot the BeagleBone, and you should now have access to the PWM pins.
+
+### Changes to the device maps
+The filesystem has also changed with 4.14. we now have a pwm device in
+`/sys/class/pwm` where we can export and then write to the PWM pins of
+of the BBB. However, in order to do this, we first need to idetify which
+pwm chip that corresponds to which pin.
+
+The address of each PWM interface is
+```
+> ls -lh /sys/class/pwm
+
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip0 -> ../../devices/platform/ocp/48300000.epwmss/48300100.ecap/pwm/pwmchip0
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip1 -> ../../devices/platform/ocp/48300000.epwmss/48300200.pwm/pwm/pwmchip1
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip3 -> ../../devices/platform/ocp/48302000.epwmss/48302100.ecap/pwm/pwmchip3
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip4 -> ../../devices/platform/ocp/48302000.epwmss/48302200.pwm/pwm/pwmchip4
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip6 -> ../../devices/platform/ocp/48304000.epwmss/48304100.ecap/pwm/pwmchip6
+lrwxrwxrwx 1 root pwm 0 Oct  7 16:40 pwmchip7 -> ../../devices/platform/ocp/48304000.epwmss/48304200.pwm/pwm/pwmchip7
+```
+Page 184 of the TI AM335x and AMIC110 Sitara Processors Technical Reference Manual gives the memory map for the PWM chips
+```
+    PWM Subsystem 0: 0x48300000
+        eCAP0: 0x48300100
+        ePWM0: 0x48300200
+    PWM Subsystem 1: 0x48302000
+        eCAP1: 0x48302100
+        ePWM1: 0x48302200
+    PWM Subsystem 2: 0x48304000
+        eCAP2: 0x48304100
+        ePWM2: 0x48304200
+```
+From this we can conclude that
+```
+ECAP0   (eCAP0) is pwmchip0
+EHRPWM0 (ePWM0) is pwmchip1
+eCAP1   (eCAP1) is pwmchip3
+EHRPWM1 (ePWM1) is pwmchip4
+eCAP2   (eCAP2) is pwmchip6
+EHRPWM2 (ePWM2) is pwmchip7
+```
+Based on the headers on the BeagleBone expansion cape
+```
+EHRPWM0A = P9_22
+EHRPWM0B = P9_21
+EHRPWM1A = P9_14
+EHRPWM1B = P9_16
+EHRPWM2A = P8_19
+EHRPWM2B = P8_13
+ECAP0    = P9_42
+```
+
+which means that we get a mapping
+```
+const pwm_pins = Dict(
+    "P9.22" => ("PWM0A", "pwmchip1", "0"),
+    "P9.21" => ("PWM0B", "pwmchip1", "1"),
+    "P9.14" => ("PWM1A", "pwmchip4", "0"),
+    "P9.16" => ("PWM1B", "pwmchip4", "1"),
+    "P8.19" => ("PWM2A", "pwmchip7", "0"),
+    "P8.13" => ("PWM2B", "pwmchip7", "1"),
+)
+```
+note that before the v4.14 kernel, this mapping was
+```
+const pwm_pins = Dict(
+    "P9.22" => ("PWM0A", "pwmchip0", "0"),
+    "P9.21" => ("PWM0B", "pwmchip0", "1"),
+    "P9.14" => ("PWM1A", "pwmchip2", "0"),
+    "P9.16" => ("PWM1B", "pwmchip2", "1"),
+    "P8.19" => ("PWM2A", "pwmchip4", "0"),
+    "P8.13" => ("PWM2B", "pwmchip4", "1"),
+)
+```
+
+### Changes to the file system
+Before the v4.14 kernel, the file system was structured in such a way that, after export, P9.22 could be enabled by writing to the file 
+```
+/sys/class/pwm/pwmchip0/pwm0/enable
+```
+however, in the new kernel
+```
+/sys/class/pwm/pwmchip1/pwm-1:0/enable
+```
+is used to enable the PWM on the P9.22 pin.
+
+### Testing the PWM pins individually
+In order to test the PWM pins from the terminal, make sure that you have added the lines in the /boot/uEnv.txt file, and then configure the desired pin to a PWM pin. For instance, if we wish to control the P9.22 pin, run
+```
+config-pin P9.22 pwm
+```
+and make sure that it is configured correctly by running
+```
+config-pin -q P9.22
+```
+which should return "P9_22 Mode: pwm". Now you first need to export the correct pin, which, according the the device mapping above, can be done by
+```
+echo 0 > /sys/class/pwm/pwmchip1/export
+```
+once this is done, we set a period and duty cycle to the pin
+```
+echo 1000000000 > /sys/class/pwm/pwmchip1/pwm-1\:0/period
+echo 800000000 > /sys/class/pwm/pwmchip1/pwm-1\:0/duty_cycle
+```
+and enable it through
+```
+echo 1 > /sys/class/pwm/pwmchip1/pwm-1\:0/enable
+```
+disable and unexport the PWM pin by
+```
+echo 0 > /sys/class/pwm/pwmchip1/pwm-1\:0/enable
+echo 0 > /sys/class/pwm/pwmchip1/unexport
+```
+Alternatively, this can be done using the Julia, by writing
+```
+p = PWM(1)
+write!(p, (1, "1"))
+write!(p, (2, "1000000000"))
+write!(p, (3, "800000000"))
+```
-- 
GitLab