Welcome to the ultimate guide on the Omega2 Dash, the latest addition to the Omega2 family that combines the Omega2 with a touchscreen TFT display.
First Time Setup
This guide will help you set up your Omega2 Dash for the first time. We’ll cover:
- Powering up the Omega2 Dash
- Using the Setup Wizard to have it connect to your WiFi network and update the software
Unboxing and Getting the Hardware Ready
Unpack the Omega2 Dash
Provide power to the Omega2 Dash through the MicroUSB port.
Turn on the Omega2 Dash using the switch.
Wait till it boots
The amber Omega status LED beside the Onion logo on the side with the TFT display should turn on and then start blinking after about 10 seconds. In about a minute, the LED will stop blinking and remain solid, this means that the Omega has completed its boot sequence!
The display will then show a welcome message:
Using the Setup Wizard
Some Computer Configuration
Your computer may need some additional programs to access the Omega through a browser:
- If you are using Windows, install Apple’s Bonjour Service
- If you are using Mac OS X, you’re all set to go
- If you are using Linux, the Zeroconf services should already be installed and you will be good to go
The Omega’s Name
Let’s find your Omega’s name before going any further.
There’s a sticker on the shielding of the Omega2S module on the Omega2 Dash
The text printed below the bar code is the Omega2 Dash’s unique MAC address, we’re interested in the last four digits. Your Omega’s name is
XXXX are the last four digits from the sticker.
So the Omega from the picture above is named
Connect to the Omega’s WiFi Network
The Omega hosts it’s own WiFi network access point. Lets connect your computer to it. The WiFi network is named the same as your Omega and the default password is
The Setup Wizard
Open your favourite browser and navigate to
XXXX are the same characters from the network name above. If the page doesn’t load, you can also browse to
You have now arrived at the Setup Wizard, hit Continue to get started:
Login with the Omega’s default credentials:
username: root password: onioneer
Connect to WiFi
After you’ve logged in, the Omega will scan the environment for available networks and will show the results in a list. In our case, we want to connect to the WiFi network (creatively) named
MyWiFiNetwork, so we’ll go ahead and click on it:
This will open a prompt to enter the network password, if the network requires a password:
Notice how you’ll only be able to click Join when the password length requirements have been met:
Once you click Join, your Omega will attempt to join the network. This might take up to a minute.
It’s possible that your computer will disconnect from the Omega’s WiFi Access Point, make sure to reconnect if that happens!
When to Omega starts connecting, the Blue WiFi LED on the Omega2 Dash will start to blink.
When the connection is successful, the LED will turn solid, and the setup wizard will let you know the connection is successful before moving on to the next step.
Last step! Now that your Omega is connected to the internet, it will check if software updates are required.
If updates are available, you’ll be able to update by clicking the Update Now button.
Something really important to remember about the update process: it’s absolutely critical that you keep your Omega plugged in and powered on during the update process. The whole process will last about 5 minutes and then you’ll be ready to start making awesome things with your Omega:
Your Omega will download the updates and install them. The amber LED on your Omega will be blinking at this point.
Finally, your Omega will reboot and initialize the new software. You’ll know everything is done when the amber status LED on your Omega stops blinking and remains on.
When that happens, press Continue. That brings us to the end of the Setup Wizard, your Omega is now configured and ready to go!
From now on, when you point your browser to your Omega, you’ll be taken directly to OnionOS.
The Setup Wizard Didn’t Work for me!
What’s next? Where can I get more information?
If you’re interested in the web-based OnionOS virtual desktop, check out the OnionOS getting started guide.
Using the Omega2 Dash
Here we’ll cover some of the awesome things you can do with the Omega2 Dash.
Removing or Changing the Boot Message
By default, the Omega2 Dash is configured to show this “splash screen” when it boots:
/etc/rc.local script mechanism is used to draw this splash screen right when your device finishes booting.
Read more about running commands automatically at boot in our documentation.
Removing the Boot Message
/etc/rc.local script file and you’ll see something like the following:
# Put your custom commands here that should be executed once # the system init finished. By default this file runs the # Omega2 Dash initialization script. # disable the blinking cursor echo 0 > /sys/class/graphics/fbcon/cursor_blink # display the splash screen text /usr/bin/o2-dash-init > /dev/tty1 exit 0
This line is the one that writes the spash screen to the display:
/usr/bin/o2-dash-init > /dev/tty1
To stop the boot message from being displayed every time your Omega2 Dash boots, comment out the line by adding
# to the beginning:
#/usr/bin/o2-dash-init > /dev/tty1
Save your changes and exit. Next time you turn on the Omega2 Dash, there will be no boot message.
Btw, you’ll notice how we also disable the blinking cursor. You can comment out that line as well if you want to keep it enabled.
Changing the Boot Message
Instead of completely removing the boot message, you can change it to whatever you like.
Breaking down the command from above:
/usr/bin/o2-dash-init > /dev/tty1
You’ll see that the output of the /usr/bin/o2-dash-init script gets written to the Omega2 Dash’s display device,
/dev/tty1 (more on that below). If you open
/usr/bin/o2-dash-init, you’ll find that it’s a shell script like any other.
Change the text output of the
o2-dash-init script, and you’ll change your boot message. Simple!
Backlight is controlled by GPIO21 (PWM Channel 3)
- 100% duty cycle = min brightness
- 0% duty cycle = max brightness
# set to 50% brightness
omega2-ctrl gpiomux set uart2 pwm23 onion pwm 3 50 120
# set to max brightness omega2-ctrl gpiomux set uart2 pwm23 onion pwm 3 0 120
The second-last argument controls the PWM duty cycle ie the brightness of the screen.
Writing Text on the Display
By default, the framebuffer is connected to the
/dev/tty1 virtual device.
So, whatever is sent to
/dev/tty1 will be displayed on the screen.
Try it out:
echo "Hello world, it's the Omega2 Dash" > /dev/tty1
To clear the screen:
clear > /dev/tty1
But that’s not all, using ANSI escape characters we can add color!
echo -e "\033[94mWow\033[0m! So \033[92mmuch\033[0m \033[91mroom\033[0m for \033[4mactivities\033[0m" > /dev/tty1
Looking at the command it might seem confusing but it’s straightforward.
\033acts as an escape character
[94msets the color to bright blue
Wowis the text
\033[0mresets the text to default.
Taking this one step further, we can incorporate ANSI escape characters in our scripts and programs.
For example, check out this Python program that loops through the available colors:
import sys for i in range(0, 14): for j in range(0, 16): code = str(i * 16 + j) sys.stdout.write(u"\033[38;5;" + code + "m " + code.ljust(4)) print(u"\033[0m")
Run it on your Omega2 Dash and pipe the output to /dev/tty1:
python3 color.py > /dev/tty1
We’ve also put together a little Python script that makes it easy to color your text.
python3 colorMessage.py > /dev/tty1
Source code available on GitHub.
The Omega2 Dash uses a small application called
fbi to draw jpg and png images to the TFT display. It comes preloaded as part of the operating system on the Omega2 Dash and it’s actually really handy.
First, disable the blinking cursor
Before we start, let’s disable the blinking cursor on the display so it doesn’t get in the way of our images. Run this on the command line:
echo 0 > /sys/class/graphics/fbcon/cursor_blink
More info on controlling the display can be found on the Omega2-Dash repo on GitHub.
Displaying images from the Omega’s filesystem
First and foremost, let’s display an image that we have on the Omega’s filesystem.
If you’re curious about how to transfer images to your Omega, see our documentation article on the subject.
The command is straight-forward:
fbi -a -d /dev/fb0 -notty -nocomments --noverbose <PATH TO FILE>
We have an
onion-logo.png file in the
/root directory, so we can do this:
cd /root fbi -a -d /dev/fb0 -notty -nocomments --noverbose onion-logo.png
When the image is displayed, you can choose to leave it there, or hit Enter to clear the screen:
Note that if your image does not exactly match the 320×240 resolution of the display, your fbi command should include the -a option for automatically scaling the image.
Downloading and displaying images
It’s also pretty handy to download an image from the internet and display it. We’ve put together a small script to do just that, it can be found here in the Omega2-Dash repo on GitHub.
The script will download the image file to the Omega, name it with a timestamp, and display it to the screen. Here’s how to run it:
sh image-dl-display.sh <URL TO IMAGE>
A festive example:
sh image-dl-display.sh https://deepundergroundpoetry.com/images/uploads/poemimages/330742.jpg?1545072728
One more thing, you can also display images one after the other, like a slide show. Just add the images to the fbi command:
fbi -d /dev/fb0 -notty -nocomments --noverbose <FIRST IMAGE> <SECOND IMAGE> <THIRD IMAGE> <ETC>
Hit Enter or Space to move on to the next image
We had a nice little collection for our slideshow:
fbi -d /dev/fb0 -notty -nocomments --noverbose onion-logo.png omega2-pinout.png map.png img_2019-12-23_16-24-09.jpg img_2019-12-23_16-08-38.jpg img_2019-12-23_16-22-47.jpg
At some point, you’ll run into a situation where you want to capture what’s on the display of your Omega2 Dash. Luckily, it’s possible to take a screenshot with ffmpeg!
A little bit of setup is required. First, you’ll need to enable the OpenWRT package repos, see our documentation article on the subject for a step-by-step guide.
Next, we’ll install ffmpeg:
opkg updateopkg install ffmpeg
Now ffmpeg can be used to take screenshots of whatever’s on the display.
But instead of memorizing a long command, you can use this bash script:
## create a screenshot from what's currently on the display
ffmpeg \ -vcodec rawvideo \ -f rawvideo \ -pix_fmt rgb565 \ -s 320x240 \ -i /dev/fb0 \ \ -f image2 \ -vcodec mjpeg \ screen-shot-`date +'%s'`.jpg
When the script is run, you’ll get a jpg of whatever is on the screen, named according to the current time and date.
The screenshot script can also be found on the Omega2-Dash repo on GitHub.
LVGL Quickstart Template
To make GUI development for the Omega2 Dash quick and easy, we’ve designed the Omega2 Dash to be compatible with the LittleV Graphics Library. LittlevGL (lvgl) is a free and open-source graphics library for C and C++that has everything you need to create an embedded GUI with easy-to-use graphical elements and visual effects. Take a look at the LittleVGL website to get an idea of the available graphical elements and themes.
To get started quickly with building your own UI for the Omega2 Dash, we’re sharing our lvgl quickstart template for C! It’s a pre-configured lvgl C project that supports drawing to the Omega2 Dash display and reading touch input. It also includes a makefile and instructions to build it as an OpenWRT Linux package.
You can use this template as a time-saving starting point for building your own UI for the Omega2 Dash!
We’ve added ~10 lines of demo code that draws a button and executes a callback whenever it’s pressed. Start there and build your own amazing UI.
Cross Compiling the LVGL Template Made Easy
The Github repo also has a script to cross compile the code for the Omega2 platform. Using Docker and the OpenWRT SDK, it provides a quick and easy method for cross compiling. It’s just one command! Learn more here.
We’ve also included instructions on how to further modify the template to suit your needs. The instructions cover how to use additional libraries in the code, and how to change the name of the software package created when cross compiling. See more here.
Micropython & LVGL
So that it’s super easy to get started creating GUIs, we’ve worked to make Micropython with built-in LVGL support available for the Omega2 Dash!
This is a great way to quickly prototype and build your GUI. Since Micropython is an interpreted language, code changes and design iterations are very quick since it just consists of changing the code and running the program. (As opposed to the process with C: changing the code, compiling, transferring to the device and then running)
On top of that, you take advantage of Micropython being easier to read and write than C and the fact that it’s a high level programming language – opening the door to object oriented programming and interaction with the web.
Installing LVGL Micropython
Make sure your Omega2 Dash is connected to the internet, then run:
opkg update opkg install lv_micropython
And that’s it!
Running LVGL Micropython
The Micropython REPL can be useful for running commands interactively. Activate it by just running:
You’ll need to press
Ctrl+d to exit.
But you’ll likely want to run your own scripts. After all that’s the most fun! Run micropython and pass the path your script as an argument:
micropython <PATH TO SCRIPT>
To get up and running quickly, you can try running the example lvgl+micropython scripts we have on GitHub.
First, try fbtouchtest.py to test out basic animations and pressing a button. We’ll download the script to the /root directory and then run it:
wget https://github.com/OnionIoT/lv_micropython/raw/master/examples/onion/fbtouchtest.py -O /root/fbtouchtest.py
Try pressing the button that shows up!
Next, we’ll try the fbdragtest.py example where you can use the touch input to drag an image around.
Same as before, we’ll download it to the /root directory and then run it:
wget https://github.com/OnionIoT/lv_micropython/raw/master/examples/onion/fbdragtest.py -O /root/fbdragtest.py
Try using your finger to drag the little box!
More Utilities and FunctionalityThe baseline Micropython installation the micropython interpreter and the LVGL library. But if you’ve ever used Python, you know there are many useful modules out there that can be installed alongside Python itself. The same holds true for Micropython! To this end, the micropython folks have made a micropython-lib project that acts like a “standard” library. It includes many useful modules like json, os, mqtt, http, pip, and many others. To install micropython-lib on your Omega2 Dash:
- Follow the instructions above to install lv_micropython
- Enable the OpenWRT package repos on your device by following this documentation article
- Install the micropython-lib package but make sure it does not install regular micropython:
opkg install micropython-lib --nodeps
Where to get helpResources for using Micropython and LVGL:
GPIOs & Expansion Header
The Omega2 Dash features a 30-pin Expansion Header that gives you easy access to the GPIOs, and allows you to connect Omega2 Expansions directly.
To learn more about using the GPIOs, electrical ratings, and pin multiplexing, see our GPIO documentation article.
The Omega2 Dash is compatible with the existing ecosystem of plug-and-play Omega2 expansions.
The Status LEDs
The Omega2 Dash features two LEDs to provide visual feedback on the current status of the device:
|Amber System status LED||Whether Linux OS has booted|
|Blue Wi-Fi status LED||Connection to a Wi-Fi network is active|
And what the behaviour of the LEDs indicates:
- System status LED
- Off – Device not powered on
- Blinking – Booting/updating
- On – Up and running
- WiFi status LED
- Off – Not connected to WiFi network
- Blinking – Connecting
- On – Connected