Quick Start
Board Setup and Exploration
This section explains the initial setup steps required to prepare the Gemstone development board for use and demonstrates how to connect to Gemstone from your computer. In later sections of the documentation, software/hardware development processes and various project examples will be examined.
By the end of this section, you will gain experience in the following topics:
- Downloading and using the Gemstone Imager software installation application.
- Preparing a new Gemstone development board by installing the necessary software.
- Connecting to Gemstone and exploring the system.
Package Contents
Todo: Image of the package and its contents
The hardware required for setup is listed below.
After the initial setup, you can connect to your Gemstone board using an Ethernet cable or use the board directly as a computer with the following hardware.
Todo: Image showing all hardware and requirements
1. Setup
Your board will be prepared by performing the following four main steps.
Download the image writing application
This is the process of downloading the desktop application used to install and customize the operating system on the board.
Write the image to the development board
This is the process of installing software on the board and preparing it for use using the Gemstone Imager application.
Change the Bootmode switch to boot the development board from the SD card
The development board can optionally be used with SD card or eMMC. This step shows how to make this selection.
Establish a connection between the computer and the development board
These are the steps to connect to the development board and access the system inside it.
1.1. Image Writing Application
All core software on Gemstone, such as the Operating System, Bootloader, and Firmware, is installed using the Gemstone Image Writer (GemImager or Gemstone Imager) application. Download the appropriate application (Linux, Windows, or macOS) for your computer from http://www.t3gemstone.org/software.
Throughout the documentation, the terms Gemstone Imager and Gemstone Image Writer will be used for the image/operating system writing application.
1.2. Image Writing Process
1.2.1. Connect the SD card and reader to the computer
The Product does not include an SD card. After connecting any brand and model of SD card with at least 32GB capacity to your computer using a suitable SD card reader, launch the Gemstone Imager application.
Todo: Connecting the SD card and reader to the computer
1.2.2. Launch the Gemstone Imager application
If you are using the Windows operating system, double-click the downloaded .exe file to install and launch the application from the Desktop.
If you are using the Windows operating system, double-click the downloaded .exe file to install and launch the application from the Desktop.
For the Linux operating system, after downloading the .AppImage file, right-click it, open the Properties screen, and check the “Allow executing file as program” option under “Permissions.”
For the macOS operating system, double-click the downloaded .dmg file to install it.
Gemstone Imager welcome screen (Note: version number may vary)
1.2.3. Select the development board
Click the “Gemstone board / Choose Device” button to select the development board you own.
This example is for the T3-GEM-O1 model.
1.2.4. Select the operating system to install on the board
After selecting the development board (Gemstone board / Choose Device), click the Operating System / Choose OS button for the next step.
Operating system image type
Gemstone uses a Ubuntu/Debian-based operating system, with different variations available depending on project needs. While the later sections of the documentation explain which version to use for which projects, a summary is provided below:
-
Desktop: An image containing applications such as a browser (Firefox), text editor, code development environment (VSCode), and video player (VLC), allowing the board to be used as a computer. This image is larger than the other two types and is mostly used for prototyping, testing, and development activities. (For robotics projects, the “Minimal” image is more suitable.)
-
Kiosk: An image that does not include the applications or desktop environment found in the Desktop image, primarily used for touch panel purposes. (For example, the touch media control panel in Tesla vehicles or the control screen in passenger vehicles during Teknofest competitions.)
-
Minimal: This image contains a real-time Linux kernel and is optimized for IoT, robotics, and autopilot applications. It is a powerful and deterministic structure suitable for embedded software system development projects.
1.2.5. Select the storage device (SD card/eMMC)
After connecting your SD card and reader to your computer, the Gemstone Imager application will list the relevant device as shown in the screenshot below.
SD card or eMMC selection
After completing all three options, click the Next button as shown below.
1.2.6. Customize the system
After completing the above selections, clicking the Next button will automatically open the System Customization screen. This screen is used to set the board’s login password and enable certain services to start automatically.
After customization, click the Save button to proceed to the next step.
1.2.7. Start the writing process
After completing all the above steps, you will be asked to confirm before starting the image writing process, and the copying process will begin.
1.2.8. Insert the SD card
After the writing process is successfully completed, remove the SD card from the reader, insert it into Gemstone, and set the Bootmode pins to “SD card” as explained in the next section.
Todo: Insert the SD card
1.3. Bootmode Switch
is used to determine how and from where (which disk the operating system boots from) the system will start when power is first applied to the board, or for purposes such as during software development.
The table and screenshot below list all Boot modes available on the Gemstone O1 development board. This section explains the installation process for the SD card, while the eMMC (embedded disk on the board) usage will be covered in later sections.
The SD card is often preferred for quick testing and development activities due to its convenience, but data loss can occur in moving systems where vibration may occur. If you plan to use your the board on a moving platform, eMMC is a more suitable choice.
Todo: Bootmode switch image
| Boot mode | Image | Description |
|---|---|---|
| SD card | ||
| eMMC | ||
| Network | ||
| NULL |
1.4. Connect the board to the computer
After connecting the USB Type-C and Ethernet cables from the package to your computer and the development board as shown in the photo below, you are ready to explore the board!
Todo: Connecting the SD card and reader to the computer
2. Exploring Gemstone
The following steps are for using your Gemstone development board via your computer. (For example, connecting to your Gemstone board’s desktop via a browser or performing operations via Serial Port/Terminal from the command line). If you have the option to connect a monitor, keyboard, and mouse, you can also explore the board using this method!
After setup, you can determine whether the board has a network connection via the connected Ethernet and USB Type-C or Wi-Fi settings (as explained in the Customize System section) by checking if the .
Todo: Connecting the SD card and reader to the computer
Serial Port
Connect to the board using a USB TTL Serial converter.
VNC
Connect to the board via a browser (Firefox/Chrome).
SSH
Connect to the board via a Terminal/Console application.
2.1. Serial Port
The USB TTL converter cable is mostly used to connect to the board via serial port when an Ethernet connection is unavailable. Normally, when you connect your Gemstone board to your computer via a USB Type-C cable, if the “Gadgets” option under Services in the Customize System section is checked, you can connect via serial port without needing a TTL cable. However, if an unexpected issue arises during development and these features do not work, you can still connect to the board using a USB TTL cable.
An advantage of this method is that it allows you to view the console outputs of U-Boot, the preloader (Bootloader) on Gemstone boards. While network initialization must complete before outputs appear when connecting over Ethernet, outputs are visible from the start when using TTL.
2.1.1. Terminal/Console Application
For Terminal/Console operations, you can use Putty on Windows, Gnome Terminal on Linux, or Terminal on macOS. This document will use the Tabby.sh application, which works on all three operating systems.
2.1.2. Download the application
Go to the Tabby.sh website, click the Download button, and download the software suitable for your operating system.
https://github.com/Eugeny/tabby/releases
After completing the installation, run it and select the Serial port as shown in the screenshot below.
Todo: Tabby terminal and serial port
2.2. Remote Desktop Connection via Browser with VNC
Browser
2.3. Network Connection via SSH
Ethernet
2.4. Update the Gemstone Operating System
Gemstone development boards include a customized real-time Linux kernel-based Debian/Ubuntu operating system. While the version you installed via GemImager is up-to-date, you can update any existing Ubuntu/Debian packages using the method below.
The following operations should be performed on the board via the command line by clicking the Terminal icon in the top menu when connected via remote desktop from a browser or via SSH/Console from your computer’s Terminal. If you have no prior experience using Linux, you can gain experience by reading the Beginner’s Guide in the Training Guides.
3. Conclusion
This document will provide explanations about Gemstone Development boards’ entire software and hardware ecosystem, along with rich project examples, and will explain how to specialize in topics such as the operating system and hardware architecture. For example, if you are interested in the Real-Time Ubuntu/Debian-based Linux distribution used for Gemstone and wonder how these systems are assembled or how robotic projects are safely implemented in C++, we encourage you to complete all the resources mentioned throughout the document to develop yourself and join the community with your contributions!