LOGI Bone Quick Start Guide
This is an out of the box quick start guide that will give the user the essentials information of preparing and running the LOGI-App demonstration applications on your LOGI Bone and BeagleBone Black. The guide will step you through the following items to get you up and running as quickly as possible.
- Installing the LOGI Bone onto the BeagleBone Black
- Getting and loading the pre-configured LOGI-Image
- Running the LOGI-Apps using an SSH terminal connection to the BeagleBone Black
What you will need for this guide
- LOGI Bone and BeagleBone connected to a local network
- A PC or Laptop connected to the same local network
- A pre-configured LOGI-Image or a Ubuntu
- Micro USB cable with 500mA supply current source (USB hub or USB power adapter)
- Ethernet Cable
Board Overview Diagram
Un-boxing and Connecting your new LOGI Bone to the BeagleBone Black
Congratulations on getting a brand new LOGI Bone! Let's get started with installing the LOGI Bone to your BeagleBone Black.
Figure: LOGI Bone out of the box
Installing the LOGI Bone on the BeagleBone Black
1) Ensure that when you install the LOGI Bone onto the BBB that you properly align the LOGI Bone cutout with the BBB Ethernet connector as shown in the below image.
Figure: LOGI Bone and BeagleBone alignment for installation
2) With LOGI Bone cutout aligned with the BBB ethernet connector place LOGI Bone P8 and P9 header connectors onto the BBB P8 and P9 sockets as shown in the below image. After ensuring the LOGI Bone and BBB connectors are properly aligned lightly press the LOGI Bone header pins into the BBB sockets until fully seated. The finally seated position of the LOGI Bone on the BBB can be seen below.
Figure: LOGI Bone fully installed onto the BeagleBone Black
Getting your LOGI-Image installed onto your SD card
The easiest way to start using the LOGI-Boards is to use the pre-configured LOGI-Image. The LOGI-Image is based upon Ubuntu and contains all of the LOGI-tools and the LOGI-Apps to get you started immediately.
Download the Latest Logi-Image
You can access our pre-configured Logi image that contains everything you need to get going with the LOGI boards.
Latest LOGI Bone Ubuntu image: http://valentfx.com/doc/logi-image/logibone/logibone_150429_ubuntu-14.04-console-armhf-2014-08-13.img.zip user: ubuntu pass: temppwd
Loading the Image
The image requires a minimum of 4GB SD card be used. The image can be loaded on an SD card on windows or on a linux system. For windows it is recommended that you use Win32DiskImager and for Linux use USBImageWriter or by using the command line disk utilities.
Creating your own LOGI compatible image
Here are some instructions on creating your own BeagleBone Black image and how to install the LOGI-Tools manually.
More Image Resources
For in depth instructions on BeagleBone Black images, writing your image, customizing images and much more, see the ADA Fruit BeagleBone Black Image guides here.
Running the LOGI Image For The First Time
Writing the LOGI Bone EEPROM configuration contents
For users who are using the pre-built LOGI Image you will need to run a setup script to write the EEPOM contents of the LOGI Bone. Depending on the contents of the BBB emmc card, it may be required for the user to hold doown the boot select button when running the LOGI image for the first time.
Once fully booted, the user will need to run the eeprom setup script so that the BBB device overlay is automatically loaded up on each boot up.
The following list contains what this script will do.
- Installs the LOGI loader which is used to configure the FPGA
- Write the contents of the EEPROM with the proper device tree configuration that will properly configure the BBB peripherals and IO upon each boot
- Updates needed libraries and tools
- Installs the LOGI python tools to read and write from the BB
A restart will be required for the changes to take effect.
Running the LOGI-Apps using an SSH terminal connection to the BeagleBone Black
Using an SSH client to remotely access your BeagleBone Black is a very flexible and powerful tool. By using SSH you are able to work on a remote client while still having full access and control of the BeagleBone Black. The BeagleBone Black can be setup at remote location while still be able to have full access to controlling the BeagleBone Black. The SSH client can reside on a PC, laptop or even smartphone. There are a couple of steps required in getting an SSH connection setup, which we will cover here.
To get started you will need to plug your BeagleBone Black into your local network. Generally your home or office network will have a router and or switch that hosts the DHCP sever. The router is your router is the gateway to the internet on on the internet side and handles the local devices using DHCP on your home or office local network. You will need make sure that the computer that you plan to access the BeagleBone Black from is on the same local network as the BeagleBone Black.
An overview of the steps that will need to take place in order to create your SSH terminal connection to the BeagleBone Black are as follows
- Plug the BeagleBone Black into your local network that support DHCP (all networks should)
- Find the IP Address that was assigned to your BeagleBone Black
- Login into your router and view the DHCP client list to access the IP Address
- or use AdvancedIPScanner to scan you network and give you the IP address assigned to the BeagleBone Black
- Use an SSH/SCP client to login into your BeagleBone Black
1) The first step to accessing your BeagleBone Black is to plug it into the network using an ethernet cable.
Finding Your BeagleBone Black’s IP Address
Before connecting to your BeagleBone Black you will need to know the IP address where your BeagleBone Black resides on the network. The Logi-image is configured with Dynamic Host Configuration Protocol (DHCP) by default so that no matter what your subnet address is, you will be able to successfully access your BeagleBone Black from the network.
After connecting your BeagleBone Black to the network you will automatically be assigned an address by your DHCP server, usually your local router on the network. You will need to determine the assigned IP address that was assigned to your BeagleBone Black. There are 2 methods for finding out what this address is.
- Log into your router and view the DHCP client table
- Use IPScanner which will scan your network and return the IP addresses of clients on the network
2) Accessing the DHCP table by logging and viewing the address assigned to your BeagleBone Black. In this case you can see that “” was assigned 192.168.0.105 . The process of logging into your router will vary from device to device. You will need to read the documentation on your router to find the login details. In my case the router address is 192.168.0.1 and the login information is user: admin pass: admin.
3) Using AdvancedIPScanner to find the addresses on your local network. The IP scanner will scan the selected range on your local network and list any devices with associated IP address and other associated network identification data. Note that this method works well in the case that your BeagleBone Black is configured with a static IP address and your don’t know what it is - as the address will not show up in the DHCP table of your router. From the figure below you can see that the “BeagleBone Black Foundation” device is showing up on the network at the expected address of 192.168.0.117.
Connecting to the BeagleBone Black using SSH
There are many SSH/SCP clients that make connecting to your BeagleBone Black from a PC an easy process. There are many available SSH/SCP Clients available. We recommend using Secure Shell Client or Bitvise SSH Client which is both SSH/SCP clients that make connecting and transferring files between your BeagleBone Black and PC an easy process.
Now that you know the IP address of your BeagleBone Black you can use an SSH client to access your BeagleBone Black.
We will be showing how to connect to the BeagleBone Black using Bitvise SSH Client . The following login steps for SSH will be very similar for any of the many SSH/SCP clients that are available, thus this guide will still be useful if using alternative clients.
The LOGI Bone works well with both Ubuntu and Debian and we have provided both images pre-configured with the LOGI tools. The steps below will only vary with the login information depending on whether you are using Ubuntu or Debian. Please make note of which version you are using and use the proper login information for this version. The following steps will be using an Ubuntu image.
Debian Image default username and Password: user: debian<strong> </strong>pass:<strong> <strong>temppwd</strong></strong>
Ubuntu Image default username and Password: user: <strong>ubuntu </strong>pass:<strong> <strong>temppwd</strong></strong>
1) open Bitvise SSH Client and select the quickconnect button which will allow us to input our SSH login information
2) Enter the found IP address found earlier, username and password for the image and the default port number = 22.
3) Press the Login button and bitvise will begin to try to connect to the BeagleBone Black.
4) Enter the logi-image password: temppwd and click OK.
5) If all of the fields were entered correctly bitvise will log you into the BeagleBone Black using SSH. Bitvise will open an SSH terminal window and an SFTP file transfer window by default. We will only be using the terminal window to run the logi-apps, but you can experiment with transferring files to and from your BeagleBone Black using the SFTP client. This is very handy when you start developing your own FPGA projects and need to transfer the bitfiles that will be loaded into the FPGA from the BeagleBone Black.
Setting up the BeagleBone configuration EEPROM
The Beaglebone requires the pins and peripherals be setup upon boot using a device tree overlay. Alternatively the user can configure the eeprom on the LOGI Bone which will be read upon boot and automatically configured so that the users is not required to setup the device tree overlay each time that the BeagleBone is booted.
To setup the EEPROM the user will need to run a setup script that writes the configuration data to the EEPROM. Additionally this will update any needed libraries and drivers for the logi-tools to run properly.
To run this script follow theses steps
- Navigate the logi-tools directory: " cd ~/logi-tools "
- Run the "install_logibone.sh" script: " sudo ./install_logibone.sh "
- When the script has finished running reboot the BeagleBone which will put the changes into affect: " sudo shutdown -r now"
Note that each time the BB boots up, it will now check the EEPROM contents and configure the peripherals and IO accordingly. You can always view the boot process and specifically regarding the LOGI setup by running "dmesg | grep LOGI". from the command line. You should be able to see that the device tree slots have been configured with LOGI overlays.
Image: EEPROM setup process to have device tree auto configured upon each boot
Each time the BeagleBone is booted, it will check the EEPROM contents that were just stored which will properly setup the IO and peripherals.
We are now ready to run the LOGI-Apps after having successfully logged into the BeagleBone Black using an SSH terminal window
You can now use the command line as you would under any linux operating system or as you would from an SSH terminal window. Try typing in "ls" to view the contents of the current directory. You will see the contents of the "home" directory including a directory labeled "logi-apps". In short, the LOGI-Apps are a "plug and play" way of running the LOGI demo projects. We have packaged all that you need into each of the "Apps" so that you can simply run "sudo ./make_demo.sh" from within the App directory and everything else will be taken care of for you. We use the "make_demo" shell script to compile any needed code, update packages, configure the BeagleBone Black, handle any other house keeping and then Load the FPGA with the bitsream and run any needed executables on the BB to complete the application. Sometime we just want to watch a move, not understand how the movie is made. So, sit back, relax and enjoy the movie.
For a Full overview of the LOGI-Apps, available LOGI-Apps, links to Documentation and the projects that the LOGI-Apps are based upon see the LOGI-Apps wiki page here.
Let's run our first LOGI-App! The Blink LED LOGI-App or "hello world" is the basis of what all of the other LOGI-Apps are based upon. It is a complete FPGA project that can be run very easily from the BeagleBone Black by simply loading the FPGA project bitfile into the FPGA. This is where the LOGI-Tools come into play. In this case we call the "logi_loader" to load the bitfile from within the "make_demo" shell script. If you are interested in seeing what is in the make_demo.sh, run "nano make_demo.sh". You will be able to see the how simple this App is, just load the bitsream. Also note that in each App there is a README.TXT that has basic instructions and links to any reference documentation that might be needed to run the App.
1) Navigate to the logi-apps directory from the pi home directory. See image "Figure - Running the LOGI-Apps - SSH" below for reference.
- " cd ~/logi-apps " - This will navigate to the logi-apps directory
- "ls" - this will output all of the contents within the logi-apps directory. You will note the different directories for each App.
The LOGI-Apps is a git repository and we will be updating and adding new Apps to the as often as possible. In order to make sure you have the latest LOGI-Apps you should "update" your logi-apps repository periodically to "pull" in any updates from the remote github logi-apps repo, found here.
2) Update the logi-apps repository. See the image "Figure - Running the LOGI-Apps - SSH" below for reference.
- Enter "git pull" - This will pull in any changes and updates from the remote repository into your local copy of the repository
If for some reason the above "git pull" command give you errors you can also re-clone the repository by using the following commands
- " cd ~ " - navigate to the home directory
- " sudo rm -rf logi-apps " - DELETE the current copy of the logi-apps
- " git clone -b logibone https://github.com/fpga-logi/logi-apps " - this will create a new copy with the latest logi-apps installed.
3) You are now ready to run the Blink LED LOGI-App. Let's navigate into the blink_led_app and run it! See image "Figure - Running the LOGI Apps - SSH" below for reference.
- " cd ~/logi-apps/blink_led_app " - This will navigate into the blink_led_app directory, no matter where your current location is
- " sudo ./make_demo.sh " - This will run the App!
There should some text updates being output into the terminal window. From the output you will see that first the logi_loader (logi bitream loader) is called and will output the status of the bitstream loading, where "config success !" indicates that the bitstream has been properly loaded into the FPGA. Then you will see the contents of the README.TXT file output to the terminal with links to detailed information about the App and the project that is was based upon. It will also output a basic description and instructions regarding the App. Note that each App contains a README.TXT file with useful information regarding the App. You can manually open and read the README.TXT file by entering " nano README.TXT ", which will open the file with a command line editor, "Nano". You can scroll through and text file, copy, paste, and close the file by entering "CTL-X".
Figure - Running the LOGI-Apps - SSH
From here you move to the next section, Running More LOGI-Apps , to begin exploring the more LOGI-Apps. The Running More LOGI-Apps section will give you links to all of the LOGI-Apps projects, overviews and step by step guides.
Running More LOGI-Apps
After running the previous blink led app you will have the basic understanding of what you need in order to run more complex and fun Apps. The process is the same for the rest of the LOGI-Apps. The condensed steps are listed here for your reference.
- " cd ~/logi-apps " - Navigate into the logi-apps directory
- " ls" - will list the available apps that can be run. Each App has it's own name directory.
- "cd NAME_OF_APP_DIRECTORY_TO_RUN" - Navigate into the app you would like to run
- " sudo ./make_demo.sh " - Run the app by running the make_demo shell script. There will be instructions on the terminal output. You can also read the README.TXT
Links to Specific instructions for each of the LOGI-Apps
Bitcoin Mining Algorithm Demo App
Image Processing Demo App
Wishbone Bus Demo App
Where to Go From Here
There are many places you can go from here. You’ve successfully programmed an FPGA and now the sky is the limit. Have a look over the following sections to see what else is possible with the LOGI Bone platform.
To begin creating your own HDL projects you should go through our "Create and Synthesize a blink LED project for the LOGI Bone using Xilinx ISE" guide.
Read Pong P. Chu’s Book
There’s a great intro book by Pong P. Chu that you should read if you want to develop a sound understanding of the Verilog or VHDL languages. We currently have examples ported from this book that allows users to step thorugh the book material and learn by examples. If you are looking for a more in depth and formal walk through of how to begin using HDL this is a great choice.
Have a look at the LOGI-EDU, which was designed to support the examples from the Pong Chu books. It also has some extra goodies such as NES controllers, Audio output and Servo interfaces to support many applications after you have used to in conjunction with Pong Chu's books.
Visit Hamster's Wiki to access his FREE FPGA course and Projects
Hamster has an excellent open source and free course that you can access on his wiki. Hamster has some of the best material I have come accross and most importantly gives full explanations and background of his projects.
LOGI Repsository with logi-apps, projects and drivers
Head over to our logi repository where can find a number of ways to kickstart your FPGA experience.
The logi-projects are open source projects that contain all of the source for you learn from and to customize your own projects. This is where you find the complete projects source for the applications run in logi-apps.
Once you are ready for you can get started creating your own projects by using any of our drivers. We provide easy to use drivers that will allow you to get a head start on your own projects.
LOGI Projects and Users projects documenation
We will be documenting all of our projects using the wiki. You can find detailed guides and documentation related to the projects you find in our repository. We also allow users to submit your projects and create some base documentation to showcase your projects.
Want to get involved in a project?
In the logi/user projects wiki there will be a section "get involved' that will have a listing of potential items that anybody can take on to contribute and get involved in the project.
Integrate a PMOD and Arduino Modules and Shields
The PMOD headers on the side of the LOGI allow for easy connectivity to off-the-shelf electronics modules. You can easily add things like GPS, Audio Amplifiers, OLED displays, Wifi, Networking, RS232, DACs, ADCs Accelerometers, Motor Drivers etc. to your design!
Open Cores hosts great open source HDL cores that you can use in your own projects.
LOGI - Repository - Projects, Libraries, Drivers
LOGI Bone Schematics
LOGI Bone User Guide -LOGI-Bone documentation
LOGI Projects wiki - LOGI and Users projects will be documented here