Purpose

This user guide will walk you through upgrading the operating system on a V5 Micromarket kiosk from Cent-OS7 or Ubuntu 14.04 to Ubuntu 20.04 or newer. Operating systems must be periodically upgraded to ensure they still receive maintenance updates from the OS vendor. This includes important security patches.

To determine if your devices are eligible for this upgrade, please see the article Determining If Device Requires Update – V5 & Ready Touch. 

Process

Before Upgrade

Preparation before going onsite

• Make sure you have login credentials for ADM and an account PIN to cash out the kiosk before upgrading. If you do not know your PIN, refer to the article Driver Login Screen.
  
  
• Be aware that your kiosk must be online to upgrade.
  
  
• Have the serial number readily available in case it cannot be found on the kiosk itself.
  
  

Verify Your Parts Kit and Tools

To complete this upgrade, you will need: 

1. #2 Screwdriver 
2. Ubuntu bootable USB flash drive (ordered from 365).
3. Mobile phone with a camera (optional: used for lighting and taking a picture of the serial number).
4. Spare PC (used in case upgrade fails and PC needs to be swapped).
5. Wire Cutters (optional: used to cut zip ties if needed).
6. USB keyboard and mouse (wired is recommended).
7. Spare OptConnect (used for a backup internet connection)

Locating Your Serial Number

Once you are on-site, check if your kiosk has a serial number sticker on the side. The serial number will begin with the prefix VSH followed by six digits.

It is recommended that you take a picture of the serial number, as you will need it later for provisioning the V5 software. If the sticker is missing, the VSH is sometimes also printed on the inside of the kiosk behind the screen/display.

Checking All Peripherals

Check all peripherals to ensure they are in good working order before the upgrade. If there is a peripheral not working, determine the cause and try to resolve the issue first.

If the kiosk uses a web camera connected to the CPU via USB, unplug the camera from the CPU before starting the upgrade process. If the camera is not removed, there is a slim chance that the device will need to be replaced after the upgrade. 

Cashing Out the Kiosk

If the kiosk has a Bill Acceptor, run a Cash Out report and remove the cash before starting the upgrade. Refer to the article Driver Login Screen and Exit Screen Feature document on how to access the Cash Out button.

Upgrading to Ubuntu 20.04

Opening the Kiosk

1. Remove the two screws from the back of the top bezel of the kiosk using a #2 Phillips Head screwdriver. 
   
   
2. Carefully open the kiosk. We recommend that you support the front of the kiosk in service position with a Roller Stand, which can be purchased from your local home improvement store.
   
   

Using the Bootable USB

1. Once the Kiosk is open, remove the USB for the webcam prior to inserting the provided Bootable USB Flashdrive into any available USB port.
   • Leave the webcam unplugged until the upgrade is complete.
     
     
2. Plug in your USB keyboard. Again, momentarily unplug periferals if needed.
   
   
3. Close out the Point of Sale (POS) application with your keyboard by pressing the keys ALT and F4 at the same time. This will take you to the desktop.
   
   
4. With the POS closed, press ALT + CTRL + T at the same time. This will bring up the Terminal window. If the Terminal does not appear, you can also navigate to it.
   There are two ways to navigate to the terminal depending on which OS is running on the kiosk. Both ways are shown below.
   • Launching the Terminal: Option 1
     Select the Applications menu in the top left-hand corner. If you don’t see Terminal listed as an option here, scroll down to System Tools, and the Terminal application will be listed here.
     Launch the terminal and proceed to step 5 below.
     
     
     
   • Launching the Terminal: Option 2
     Select Applications in the top left-hand corner, then select Accessories. From here, you will see the Terminal application listed. 
     Launch the terminal and proceed to step 5 below.
     
     
5. With the terminal window selected, type the command shown below. There are two spaces in this command: one space is between "sudo" and "kiosk-udpater.sh", and the second space is between "kiosk-updater.sh" and "—update-scripts". Once the command is typed in, press Enter.
   sudo kiosk-updater.sh --update-scripts

   It should take around 5 seconds to run this command. If the terminal is asking for a password after the command has been entered, or if it only takes about one second for the command to run, a typo has occurred.  Check for mistakes in the command, and run it again. 
   
   

   
6. Once the command has completed the compiling process, type in the next command shown below. There are two spaces in the command below: the first space is between "sudo" and "kiosk", and the  second space is between "updater.sh" and "—run"). 
   sudo kiosk-updater.sh --run-kiosk-fix-script=add-grub-clonezilla-usb-boot
   
   
   
   
7. Once this command is finished running, reboot the kiosk.
   
   
8. When the kiosk boots back up, it should be on a screen like the ones shown below. The screen might have a green background, but it will have a similar list of options. The screen will time out in 5 seconds if no keyboard activity is detected, and will then boot back up to the regular point of sale screen.
   
   
   
9. Navigate to the Clonezilla USB option using your keyboard's arrow keys. While the USB option is selected, press Enter. Note that the orientation of the screen might be incorrect, but this  will correct itself once the upgrade process is complete.
   
   • If Clonezilla is not showing in the list of options, run the following command:
     sudo kiosk-updater.sh --force-deployment=release
     Then return to the software updater/reboot process. 
     • If Clonezilla still doesn’t show up as an option, you can attempt to boot to the USB itself by pressing F7 (W8) or F11 (S11 or W11) after rebooting.
       
       
10. You will now be taken to a screen asking for a passphrase. Please note: the passphrase is case sensitive, and will not show characters on the screen as you type. Before you type the passphrase, ensure that "Num Lock" on your keyboard is not turned on. If the "Num Lock" is turned on, you might receive a message that states the image failed to decrypt. The passphrase is: "Chipsandadrink8!".
    
    
    • NOTE: If your PC just reboots and doesn't look like the screenshot below, then retry the previous steps. If the results are the same, then this USB is corrupted and cannot be used for upgrades moving forward. Set it aside so it is no longer used. Repeat the previous steps with a new USB to continue.
      
      
11. This will start the process of re-imaging the PC to the new Operating system.
     
    
    Do NOT let the PC be powered off while this process is occurring, as the PC will become unusable
    
    The PC will show different processing screens during this process. Note that the orientation of the screen might be incorrect, but this  will correct itself once the upgrade process is complete. Example screen below.
    
     
    • NOTE: If your screen looks like one of the following screenshots below or asks you to "Press Enter to continue", power down your pc and remove the USB. Some of the screens look similar to the previous step except there is a black bar of text running across the grey dialog window.  This means the USB is corrupted and cannot be used for upgrades moving forward Dispose of the USB properly so that it is no longer used. Repeat the previous steps with a new USB to continue.
      
      
      
12. Once re-imaging is complete, the PC will power down. You may now remove the USB Flashdrive, but keep the keyboard plugged in.
    
    • At this time the Webcam USB can be plugged back into the kiosk.
      
      
13. Turn on the PC again, and proceed to the next steps.

Configuring the Kiosk after Upgrade – Provisioning the Kiosk

There are two flows that a kiosk might go through in order to be provisioned. Both of these flows are shown below.

Steps 1 through 5 of "Flow 1" will be the same for Flow 2. The steps below are proceeding after step 5 from the first flow.

Running the Provisioner – Initial steps 

1. Power up the kiosk in Provisioner Mode. You will now see the Welcome! screen. 
   
   
2. Click OK, and the Network Setup screen will appear. This screen has a list featuring Internet, Services, Network Check, and Software Updates. These items will display a green checkmark if they have loaded properly, and a red X if they have failed to load properly. If the Network Check fails, press the Check for Updates button.
   If the the Network Check still fails after four attempts, follow these steps:
   
   
   • Press the "Alt" "Ctrl" & "Del" keys on your keyboard. A window should pop asking you to Log Out (screenshot below). Click on the "Log Out" button.
     
     
   • Once you log out, select the operator account and type in the password. If you don’t have the password, please call 365 support at (888) 365-6282 so that they can provide it to you.
     
     
   • Launch the terminal located on the left side of the screen, or by pressing "ALT" "CTRL" & "T" on your keyboard.
     
     
   • Input the following command: sudo kiosk-updater.sh --reboot-after-deployment --force-deployment=release. This will update your kiosk to the latest release and reboot itself when complete. This process may take a few minutes.
     • Note: When the terminal displays "opr@VSHxxxxx:-$" you will know the command has completed. At this point, it is applying the update, which could anywhere from 10 minutes to one hour depening on your connection speeds. Please do not force the reboot unless it takes longer than one hour after the command has finished running.
       
       
   • When the kiosk boots back up it will go through it's checks again. If the update was successful, then the Network Check will not fail again.
     
     
3. The last item on the list, Software Updates, can take anywhere between 10 to 20 minutes to complete, depending on internet connectivity and how out of date the software is.
   
   
4. If the version number in the top-right corner of the Network Setup screen is:
   
   
   • -rel-230801 or higher, and all items have green check marks, select Next.
     
     
   • -rel-230601 or lower, select Check for Updates, wait until you have all green checkmarks, then select Next.
     
     If Services displays a red X with the text "Failed to reach services", follow steps in the time segment 0:51-4:00 of Troubleshooting an Offline Kiosk. If this does not address the issue, contact 365 Support at (888) 365-6282.
     
     
5. The Commission Kiosk screen now will display. Scan or type the kiosk serial number or barcode in the textbox. Be absolutely certain that this serial number is entered correctly; it is very important as this will determine if the kiosk is tied to the correct location.
   
   
   1. If upon attempting to provision the kiosk, you receive a description in the kiosk device summary that has "MKL Kiosk" listed and you see the spinning wheel screen below, you must remove the "MKL Kiosk" portion from the device summary and reboot the kiosk, followed by attempting to provision the kiosk again. The removal of the device summary should allow the kiosk provision to complete, and remove the spinning wheel screen.
      
      
      
      
   2. If there is a kiosk serial number barcode on the side of the kiosk, you can take a picture of the barcode on your phone and scan the image from your phone's screen.
      
      
   3. If there is no barcode on the kiosk, use the onscreen keyboard to enter the kiosk serial number manually. Make sure to include "VSH" at the beginning of the barcode number.
      
      Once the barcode has been entered, select Next.
      
      

There are two possible screens that may appear after you select Next. This will determine if you will finish this process by following the steps in Flow 1 - Final Steps of Running the Provisioner, or Flow 2 - Final Steps of Running the Provisioner. 

Flow 1 - Final Steps of Running the Provisioner 

5. Continuing on from step 4 of the initial steps, you will receive a message stating that the kiosk already exists. When this happens, select the red Clear Deploy Date button.
   
   
6. You will then be taken to the admin login screen. Enter the PIN 365 (leaving the last text field blank) and select Submit.
   You will then be taken back to the Kiosk already exists screen. This screen may continue to be visible for up to one minute before moving on to the next page. This is normal, and there is no need to press the clear deploy date button again at this stage.
   
   
7. Next, you will be asked to verify the kiosk’s information. If the presented information looks correct, select Next.
   
   
8. At this point, the kiosk will start syncing and updating. This can take 10 to15 minutes. It is possible the kisok will fail to sync. If this happens, select Next again. This process may need to be repeated several times.
   
   
9. You will then need to test the peripherals. Deselect any devices that might not be applicable to your kiosk. Select Begin Testing to start testing your peripherals. You will need bills to test the Bill Acceptor.
   When testing each device, a green check mark will appear if the test was successful. Once the green check mark appears, you may select the Next button in the bottom right-hand corner screen. This button may say Skip instead of Next. 
   If one or more devices fail the test, you will see a red X next to that peripheral. Contact 365 Support at (888) 365-6282 for help addressing the issue. If this peripheral is not crucial to the operation of your market, you may proceed to the next step.
   • Please note: Monnit Alta Gateways/Sensor devices may fail the peripheral test. This is normal for Alta Generation hardware, and the device should be tested for checking in using Monnit tools and processes. When a Monnit Alta Gateway is connected properly, a green hardware light should show. For comprehensive information, please see the Monnit Section of our HelpCenter.
     
     
10. Select Start Kiosk to start up the Point of Sale (POS)
    
    
11. Verify that your kiosk is online via ADM or from the kiosk itself. See Legacy & VS - Network Connectivity Verification and Troubleshooting - Operator Guide for instructions on verifying the network connectivity status, either remotely or on-site.

Flow 2 - Final Steps of Running the Provisioner

5. Continuing on from step 4 of the initial steps, the kiosk will start installing some key pieces of software and sync data to the kiosk. When that is done, you should see a Success message. Select OK to continue.
   
   
6. Enter your ADM login credentials, then select Continue. 
   
   
7. The Select a Device to Copy screen will display. You will be able to select from the Orgs and Locations you have access to in ADM.  Choose the appropriate Org, Location, and Device, then select Next.
   
   
8. The Confirm Setup screen will now display. It provides an overview of the device you want to copy, as well as the device and location where you intend to copy it to. If everything on this screen is correct, choose Confirm & Finalize. If any information needs to be changed, select Back.
   
   
9. The next step is to test out the peripherals. Deselect any devices that might not be applicable to your kiosk, then select Begin Testing to test your peripherals. You will need bills to properly test the Bill Acceptor.
   When testing each device, you will see a green checkmark if the test was successful. Once this appears, select the Next button in the bottom right-hand corner of the screen. This button might be displayed as a Skip button.
   
   
10. If all peripherals have green check marks, this means the upgrade has been successful, and your kiosk is ready for normal use. If one or more peripherals fail the test, you will see a red X next to that peripheral. Contact 365 Support at (888) 365-6282 to address the issue. If this device is not crucial to the operation of your market, you can proceed to the next step.
    
    
11. Select Start Kiosk to start up the Point of Sale (POS).
    
    
12. Verify that your kiosk is online via ADM or from the kiosk itself. See Legacy & VS - Network Connectivity Verification and Troubleshooting - Operator Guide for instructions on verifying the network connectivity status, either remotely or on-site.

Closing the Kiosk

Carefully close the front of the kiosk and ensure that no cables are pinched between the two halves.

Align the kiosk front bezel with the screw holes, and reinsert the two, 10-24 Philips head screws.

The screws must be aligned perpendicular to the front surface of the kiosk.

After Upgrade - Secure Destruction of Flash Drives 

A single Bootable USB Flashdrive can be used to upgrade multiple kiosks. When you have completed all the required upgrades, any flash drives you still have in your possession should be physically destroyed. For example, the Flashdrive could be physically smashed with a hammer or drilled into with a drill bit. Be sure to take safety precautions before physically destroying the Flashdrive. If you are not comfortable destroying the Flashdrive at the end of your project, please mail the Flashdrive to 365. 

Tips and Tricks

• Always use the Power button to turn off the kiosk: do not unplug the device in an attempt to power it off. 
• It is recommended to take a photograph of the kiosk's internal layout before you start disassembling the device, so that you may refer to the photograph while reassembling.
• Angle the PC slightly forward to aid in connecting and disconnecting devices
• You will need a #1 screwdriver to remove the appropriate screws.
• Use a "Roller Stand" or a similar product to support the front of the kiosk during service.
• Ensure that all cables are kept clear of the hinge elements of the kiosk, and are not pinched when closing the device. 
• Hold wire cutters upside down to avoid damaging cables.
• Do not turn off the router during this process.
• Clean the Fingerprint Reader if readings are inaccurate. Please see the Cleaning Instructions for Multiple Devices for information about cleaning your particular fingerprint reading device. For example, 4xxx Readers can be cleaned by applying sticky tape to the gel surface, rather than industrial cleaners or solvents.
• When disconnecting a serial / DVI / VGA connector, the posts often become unscrewed. Use a 3/16" nut driver to refasten it.
• Zip ties can be curled to more easily loop them through the holes.
• Make sure the 2x screws on the back of the kiosk are in when the service is done.

FAQ

Do we need to upgrade?

Yes. Once operating systems have reached the end of support, there will no longer be vendor updates. These updates can include things like security patches, drivers, and improvements for compatibility with the overall OS.

What are we upgrading from and to?

V5s will be upgrading from either Ubuntu 14.04 or Cent OS 7 to Ubuntu 20.04 or newer.

When do these upgrades need to be completed?

V5 and ReadyTouch devices running Ubuntu 14.04 or Cent-OS7, have support until April 2024.

What if the upgrades do not happen until after support ends? Will the markets stop working?

Functionally, nonupgraded devices will remain the same. At first, there will not be a noticeable impact. However, devices will NOT receive critical security patches offered by the vendor in the future, which will leave them vulnerable to new security threats.

How are these devices going to be upgraded?

There will need to be a technician onsite to complete the upgrade. They will follow the respective documentation depending on the device being upgraded. All devices will be upgraded via a Flashdrive.

Which kiosks do not qualify and what happens with those kiosks?

Devices that do not qualify are either already up to date with the latest OS, or the hardware is too out of date to be upgraded. Devices that are incapable of being upgraded will eventually need to be replaced.

Is there a cost for these upgrades?

No - the USBs are currently free, and there are no charges or fees.