Skip to content

Commit

Permalink
Update install documentation to match current OS images.
Browse files Browse the repository at this point in the history 
 * Don't use overlay for BUMPS anymore, just use pins file.
 * Update INSTALL instructions on the right kernel.
  • Loading branch information
@hzeller
hzeller committed Jul 10, 2022
1 parent 8afb8a6 commit be0c432
Show file tree
Hide file tree
Showing 9 changed files with 126 additions and 238 deletions.
84 changes: 25 additions & 59 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,82 +2,47 @@

## Get one of the latest linux Debian images

Download one of the latest debian images provided by the following [**list**](https://beagleboard.org/latest-images). This installation guide refers to [*bone-debian-9.3-iot-armhf-2018-03-05-4gb.img.xz*](http://debian.beagleboard.org/images/bone-debian-9.3-iot-armhf-2018-03-05-4gb.img.xz).

If necessary, check the integrity of the downloaded image by matching its sha256sum hash and the one provided on the website (on a linux terminal,
just run `sha256sum bone-debian-9.3-iot-armhf-2018-03-05-4gb.img.xz`).
Download one of the latest debian images provided by the following [**list**](https://beagleboard.org/latest-images). This installation guide refers to
[AM3358 Debian 10.3 2020-04-06 4GB SD IoT](https://debian.beagleboard.org/images/bone-debian-10.3-iot-armhf-2020-04-06-4gb.img.xz)

Always use the most minimal image you can find, e.g. no graphical user
interface etc.

## Flash the SD card
**WARNING**: **Be careful when selecting the device to be flashed, as you may end up losing data inside it.**

Connect an empty SD card to your PC and extract and copy the image over your sd card.

Based on the platform this can be done via the following methods:

#### **Linux**
On a terminal, save the SD card device path by inspecting `lsblk`. The SD card should be under a path similar to `/dev/mmcblkN`. Run on the terminal, `xzcat bone-debian-9.3-iot-armhf-2018-03-05-4gb.img.xz | sudo dd of=/dev/mmcblkN`.
Before extracting the SD card remember to run `sync` in order to flush any remaining buffered I/O operation.

#### **Linux / Mac OS / Windows**
Using the graphical tool **https://etcher.io/**. Select the downloaded image , the target device and then click on **Flash**.


## Boot

1. Connect the beaglebone to your local LAN with DHCP enabled or via USB.
2. Insert the SD card on the beaglebone slot.
3. Turn on the beaglebone.

### Connect via SSH

If you connected the beaglebone via USB, a virtual Ethernet interface should appear on your PC.


#### **Linux / Mac OS**
## Flash the SD card; Boot; SSH into your Beaglebone

Open a terminal and run: `ssh [email protected]`
the default password is usually `temppwd`.
This documentation is provided elsewhere already, see
https://beagleboard.org/getting-started

#### **Windows**

Download the ssh client from https://www.putty.org/.
use as hostname `[email protected]` and connect using the usual `temppwd` password.
In short: unpack the xz-packed image, and place as-is on the SD card (On
Linux, use `dd`, on other platforms they have more complicated graphical tools).

Then boot the Beaglebone and connect via ssh to it (
`ssh [email protected]`, default password `temppwd`).

## Prepare the environment

If the following one-liner:
```
if lsmod | grep "uio_pruss" &> /dev/null ; then echo "The kernel is BeagleG ready"; else echo "uio_pruss module not present"; fi`
```

will return `The kernel is BeagleG-ready`, it means that you can skip this section, otherwise you will need some additional steps.
To be able to use the PRU as we use it, we need the `bone` kernel (not ti).

Beagleg as it is now, requires a kernel module called `uio_pruss` (see [this](https://elinux.org/Ti_AM33XX_PRUSSv2#Communication)).
```bash
cd /opt/scripts/tools
sudo ./update_kernel.sh --bone-rt-kernel --lts-4_19
```

To enable it, you will need to edit your `/boot/uEnv.txt`
and change:
Then edit your `/boot/uEnv.txt` and comment `uboot_overlay_pru` lines but
the `PRU-UIO` one:

```
###PRUSS OPTIONS
###pru_rproc (4.4.x-ti kernel)
#uboot_overlay_pru=/lib/firmware/AM335X-PRU-RPROC-4-4-TI-00A0.dtbo
###pru_uio (4.4.x-ti, 4.14.x-ti & mainline/bone kernel)
#uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo
uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo
###
```

uncommenting (removing the `#` in front) the line `uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo`.

Before rebooting, you will also need to have an updated version of your kernel as you may suffer a bug that will not correctly load the uio_pruss module and device tree overlay.

To do so, run `sudo apt-get update; sudo apt-get upgrade` and on completion,
execute a reboot.

## Install BeagleG


Expand All @@ -92,6 +57,9 @@ change directory into the repository and run `make`.
The resulting `machine-control` binary will be in the toplevel directory. You
can `sudo make install` it, or run it right there.

Then [set up your hardware](./hardware/) and possibly create the necessary
systemd configuration for a set-up that starts on boot.

# TROUBLESHOOTING

In general, make sure to have the latest Beaglebone Debian image; most of
Expand All @@ -112,13 +80,11 @@ git pull
sudo ./update_kernel.sh
```

## uio_pruss not loaded

In some older kernels, you might need to manually

```
sudo modprobe uio_pruss
```
In particular if you see **`prussdrv_open() failed`** in the logs, this might
indicate that either the wrong kernel is enabled (if you type `uname -r`, the
returned name needs to contain `bone` (like `4.19.232-bone-rt-r75`)) or if the
`uboot_overlay_pru` setting in `/boot/uEnv.txt` is not properly enabled.
(see 'Prepare the Environment' above).

## System locks up

Expand Down
43 changes: 33 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,20 +32,43 @@ socket (you can just telnet to it for an interactive session, how
cool is that?).

## Install
For system configuration and building the `machine-control` binary, see
For detailed system configuration and building the `machine-control` binary, see
[INSTALL.md](./INSTALL.md).

## Getting started
Before you can use beagleg and get meaningful outputs on the GPIO pins,
we have to tell the pin multiplexer to connect them to the output pins. For
that, just run the `start-devicetree-overlay.sh` script with your hardware
to install the device overlay. You find it in the `hardware/` subdirectory.
two things are required on a fresh Beaglebone installation (we recommend the
IoT image).

sudo hardware/start-devicetree-overlay.sh hardware/BUMPS/BeagleG.dts
### Enable PRU

See the [Hardware page](./hardware) how to enable the cape at boot time.
(Note: this section will be simpler once we switched entirely to universal
cape).
To be able to use the PRU, we need the `bone` kernel (not ti).
```
cd /opt/scripts/tools
sudo ./update_kernel.sh --bone-rt-kernel --lts-4_19
```

Then edit `/boot/uEnv.txt` and make sure that the line `uboot_overlay_pru`
line is uncommented that contains the `PRU-UIO` firmware. The default otherwise
is `PRU-RPROC`, we _do not_ want that, so comment that line out and enable
the following `uboot_overlay_pru` line instead:

```
###pru_uio (4.14.x-ti, 4.19.x-ti & mainline/bone kernel)
uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo
```

Then reboot. `uname -a` should return a kernel name with `bone` in its
name `4.19.232-bone-rt-r75`.

### Enable Output Pins for your board

The GPIO pins used for each hardware
This is how you initialize the pins if you use the BUMPS board:
```
/opt/source/bb.org-overlays/tools/beaglebone-universal-io/config-pin -f hardware/BUMPS/bumps.pins
```

See the [Hardware page](./hardware) for more boards.

## Machine control binary
To control a machine with G-Code, use the `machine-control` binary.
Expand Down Expand Up @@ -95,7 +118,7 @@ More details about the G-Code code parsed and handled can be found in the
For testing your motor settings, you might initially just have a simple
file:

sudo ./machine-control -c my.config -f 10 myfile.gcode
sudo ./machine-control -c hardware/BUMPS/bumps.config -f 10 myfile.gcode

Output the file `myfile.gcode` in 10x the original speed (say you want to
stress-test). Note, the factor will only scale feedrate, but the machine will
Expand Down
98 changes: 0 additions & 98 deletions hardware/BUMPS/BeagleG-BUMPS.dts
View file

This file was deleted.

33 changes: 25 additions & 8 deletions hardware/BUMPS/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,26 @@ The BUMPS cape was designed together with BeagleG.

![Bumps board][BUMPS-img]

This cape uses the [beaglebone-universal-io] device tree overlay.

## Overlay and I/O configuration

The I/O pins can then be configured using the config-pin utility. Refer to the
[beaglebone-universal-io] for details.

The pin configuration can also be setup from a file such as
[bumps.pins](./bumps.pins).

```
# Configure the I/O pins
/opt/source/bb.org-overlays/tools/beaglebone-universal-io/config-pin -f bumps.pins
```

## Default configuration

An example default configuration [bumps.config](./bumps.config) has been
provided as a starting point.

## Pinout

These are the GPIO bits associated with the motor outputs on the BUMPS board.
Expand All @@ -28,19 +48,15 @@ Motor enable for all motors is on `GPIO-1`, bit 28, P9-12
can be used, but the mapping to P9-42A (P11-22) and P9-41A (P11-21) should
probably move to an unambiguated pin)

In the [Bumps cape][bumps] picture above, the X axis on the very left (with a plugged
in motor), second slot empty, third is 'Z', fourth (second-last) is E, and
finally the Y axis is on the very right (more space for two connectors which I
need for my Type-A machine).
The axis mapping is configured with:

./machine-control --axis-mapping "X_ZEY" ...
The mapping of motor number to axis happens in the `[Motor-Mapping]` section
of the configuration file, then the axes can be configured with steps etc.

If you build your own cape: note all logic levels are 3.3V (and assume not more
than ~4mA). The RAMPS driver board for instance only works if you power the
5V input with 3.3V, so that the Pololu inputs detect the logic level properly.

This is an early experimental manual cape interfacing to a RAMPS adapter:
This is how the early experimental manual cape interfacing to a RAMPS adapter
looked like.
![Manual Cape][manual-cape]

At the middle/bottom of the test board you see a headpone connector: many of
Expand All @@ -60,3 +76,4 @@ Other pins:
[BUMPS]: https://github.com/hzeller/bumps
[BUMPS-img]: ../../img/bumps-connect.jpg
[manual-cape]: ../../img/manual-ramps-cape.jpg
[beaglebone-universal-io]: https://github.com/cdsteinkuehler/beaglebone-universal-io
0 hardware/BUMPS/BUMPS.pins → hardware/BUMPS/bumps.pins
View file
File renamed without changes.
Loading

0 comments on commit be0c432

Please sign in to comment.