diff --git a/docs/build/index.md b/docs/build/index.md index b20963998205e517d0f793e84e51eb0659d860b2..a0767638a18630d0eafbfd8de46cf79c24cfc151 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 23f8f58d82d3a57100e5323ef944bda59e6abcdc..6f71a12812ff9324f0c0b419df3d303c712e8a81 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`** — *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`** — *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`** — *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`** — *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`** — *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!`** — *Function*. diff --git a/docs/build/man/development.md b/docs/build/man/development.md index c0f9e587facd498d86abd31d960f71e9f623c96a..9394339c809ec6d885ea30f73125fc868ecfa502 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 c33a812abc0acb4a7b7b570ef6b0ed2ce19b6eeb..0858bac3099fb92c86653a5539c0391b7dd05492 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 039132b16f5f3111400875704978330d8f7b5cc5..9837dfbb8d4c21b38d3ee7177b62b97b2cf81fb5 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")) +```