The Raspberry Pi 4b 5250 Terminal

This is an update (July 2022) to my article written in 2017 giving instructions on how to turn a Raspberry Pi into a 5250 terminal. The newer Raspbian OS versions (Buster/Bullseye) made some of my prior instructions invalid. There's a link at the end of the article to a Youtube video that shows these steps in detail. *note: 01/22/24 edit adds instructions on installing the UCF firewall for added security.

The new Raspberry Pi 4B 2Gb model costs around $46. Add a case, heat sinks, power supply, and an 8GB microSDHC card for around $34, and you've got the makings of an inexpensive ($80-ish) 5250 terminal.

There are two basic methods we've used with good success to create a 5250 terminal from a Raspberry Pi. First, if you have an IBM-i with active software maintenance (SWMA) and are running IBM-i 7.x, then the new IBM-i Access Client Solution for Linux is one option. Alternatively, if you're wanting a simple user interface or don't have active SWMA then the open source TN5250j project is your other option. Both of these programs are 100% java-based and thus can run on any OS or device that supports java without having to be recompiled.

The first basic assumption for our Raspberry Pi 5250 project is that we do not want a full GUI with all the bloat-ware that comes with a full Raspbian OS desktop (as of the date of this post the current version is Raspbian Bullseye). Thus, we're building this with Raspbian Bullseye Lite and adding a basic GUI. Unlike my 2017 article, I'm going to cover both the TN5250J and IBM Access Client Solutions setup this time around.

Here are the basic steps that I will outline in some detail in this article: 1) Download software and prep the microSD card, 2) Install the Raspbian Bullseye Lite OS; 3) Update and modify the Raspbian OS; 4) Copy 5250 programs and modify files; 5) Modify the boot load sequence of OS to auto-launch 5250 (if desired)

Step1: Download the Raspbian Bullseye Lite .img file zip archive and unzip. If you're a Windows user you'll need to install Win32DiskImager or Raspberry Pi Imager application. Also, go ahead and download TN5250J from SourceForge and the IBMiACS from the IBM Downloads site. If you purchased a new micro SDHC card it should already be formatted, if not format it as FAT32.

Step 2: Use Win32DiskImager or Raspberry Pi Imager to burn the Raspian Bullseye Lite .img file to the microSD card. My suggestion is that if you're going to use this microSD as a template for creating more microSD cards for more terminals, use a 4GB microSD card as your template. That way the image you'll create will be 4GB instead of 8, 16, or 32GB. Once Win32DiskImager finishes writing the .img to the microSD card, Windows will prompt you to Format the drive - CANCEL this prompt. Accept and Exit Win32DiskImager. Eject the microSD card.

Step 3: Time to hone your Linux chops or learn some new ones. Once you insert the microSD card into your pi and apply power, the OS should boot and begin asking some setup questions. As an aside, you need a USB keyboard, USB mouse, a monitor, and a network connection to complete this setup. The Pi has a micro-HDMI port so you may need a micro-HDMI to HDMI or VGA converter. The Pi will grab a DHCP network address; you can change this to a static IP later. It will first ask you for keyboard setup; the system defaults to English(GB), so scroll down to Other, select the appropriate option, in my case English (US), next, scroll to the top of the list, US (English) or another language as appropriate; OK. It will then prompt you for a default USERID and Password. You'll have to enter the password twice. For this article, I've simply used USERID: pi and PASSWORD: pi to keep things simple.

Next, let's run: sudo raspi-config and set our keyboard type, language set, time zone and WLAN country.?

sudo raspi-config ->(4)localization -> (I1)Locales->Change Locale; scroll down and un-select (using space bar) en_GB.UTF-8 (unless of course you live in Great Britain), scroll down further to en_US.UTF-8 (for those in the US), tab, OK, on the next screen arrow down to en_US.UTF-8 (or other selected locale), tab, OK (this will generate locale files); Now, go to locale > keyboard and I selected > keyboard Generic US/104 (or other depending on location). Next, set your timezone: (I2)timezone (in my case US->Central); finish (should prompt to reboot); if not, type sudo reboot at the terminal prompt.

Now for installing a base GUI without all the stock bloat-ware:

To make the RaspPi automatically boot to the GUI, use sudo raspi-config to go to Boot Option menu ->(B1)Desktop/CLI -> (B4)Desktop Autologin; tab; OK; tab; Finish; If your users are going to use IBMiACS and print reports to PDF for viewing, type: sudo apt-get install mupdf to install a PDF reader.

Step 4: Next, we'll download tn5250j-0.7.6-full-bin.zip (or the latest version) from SourceForge and unzip. Rename the unzipped folder to tn5250j for simplicity. Copy the folder to a USB stick. Insert the USB stick into the booted RaspberryPi. The GUI should automatically prompt to "Open with File Manager". Use File Manager to drag the tn5250j folder to /home/pi/ folder. For IBMiACS, create a folder on your USB stick called ibmiaccess and copy the following files from your download: acsbundle.jar, AcsConfig.properties, and logo128.png. Drag the ibmiaccess folder to the /home/pi folder. Open a terminal window and type: cd /home/pi/tn5250j or cd /home/pi/ibmiaccess <enter>, and type sudo chmod u+x *.jar to make all of the .jar files executable.

You can get the IBMiACS here: https://www.ibm.com/support/pages/ibm-i-access-client-solutions. It requires an IBM ID to log in and download the file(s).

To create a shell script for running the TN5250J program:

To create a shell script for running IBM i ACS:

To enable TN5250J or IBMiACS to auto-start when pi boots:

To add an icon to the Desktop for TN5250J or IBMiACS, go to a terminal session and type the following. Remember that Linux is case-sensitive. In each case, once you exit the Nano editor, run: sudo chmod u+x *.desktop to make the desktop file executable.

You must also go to System Tools > File Manager (launch), go to Edit > Preferences, and check the box beside: Don't Ask Options On Launch Executable File, and click Close, so that the GUI won't prompt you each time the desktop shell file attempts to launch your emulator program. At this point, if you reboot the RasPi the system should auto-login to the GUI and then launch the TN5250J or IBMiACS program (if you elected for auto-launch option above). You can then set up a terminal session to your IBM-i system (yes, you can define multiple sessions), remap your keyboard (by default the enter key on the number pad isn't mapped as Enter). You're restricted to two key maps per function in TN5250J, so if you're used to the right control key also being an Enter key, you'll have to choose. If for some reason you should have an issue with the TN5250J application locking up on launch due to a possible error in session settings, just launch a terminal session, cd /home/pi/.tn5250j *important: put the period in front of tn5250j in this case, as it is a hidden directory that contains the configuration files*. Typing pwd will display your current directory. Use ls -l to display files in the directory. You can delete the sessions file using sudo rm sessions. TN5250J will recreate the sessions file when you launch TN5250J and re-add the sessions to the configuration screen. Always remember to click APPLY. Mark the first session you create as "default" and it will auto-launch that session every time the device boots. Also, to modify sessions or add sessions, you must right-click the mouse inside the session window and the edit options panel will pop up.

The IBM i Access Client Solutions setup is a bit different. If you use this on your Windows PCs, then you're already familiar with the setup. One important mention is that if you want to RESTRICT the functions that the user can access within the IBMiACS client, you do the following: close the IBMiACS client. Open a terminal window (SystemTools>LXTerminal) and type: cd /usr/local/bin. Now, type sudo ibmiaccess.sh to launch the IBMiACS client as the ROOT user. This will give you access to a "hidden" menu that only the root user has access to. Go to Edit, and Preferences, and you'll now see a Tab named Restrictions. Check the box next to the functions that you WANT to restrict users from accessing. There's also an option at the bottom of this list to "hide restricted functions" so that users can't see what they don't have access to. Once you define a system and session and save as an .HOD file, you can insert those values into your shell program to automatically launch the emulator with the pre-defined system, session, and terminal ID.

The IBM site that lists all of the IBM i ACS startup options is: https://www.ibm.com/support/pages/ibm-i-access-acs-getting-started#7.2

If you want the Display Power Management System (DPMS) to NOT auto-sleep the display, go to the main menu (bottom left), and click Preferences > Screensaver. You can then disable the screensaver or set the timeout variable, and the Advanced tab has the DPMS settings (disabled by default). Here's my Youtube Video that shows all of these steps: https://youtu.be/Me-cefl_9qM

For added security, it is recommended to install, enable, and configure the UFW firewall application. There are plenty of tutorials available on configuring UFW on Linux.

Based on recent input, I've edited the original post to add instructions for cloning the SD card for the Pi-5250 project. Insert the SD-card into your Windows PC. For those without an SD-card slot, there are USB SD-card readers. Launch Win32DiskImager (available on SourceForge). Click the folder icon next to the Image File box, navigate to a local folder and type in the name of the image file you want to use, with a .img extension (see example below). Choose your SD-card device drive letter. It will have (2) drive letters assigned such as E and F. Pick the E: drive as the device. Now click READ at the bottom of the window. Win32DiskImager will read the SD entire card to a .IMG file. You can then insert a blank SD-card into your PC, re-launch Win32DiskImager, navigate to the .IMG file location, pick your image, choose the SD-card device drive letter, and click WRITE to create a new SD card that is a clone of your prior image.