Skip to content

Home

Jump to bottom
unreasonableman edited this page Nov 21, 2022 · 42 revisions

Table of Contents

  1. What is GRaaS?

  2. History of GRaaS

  3. GRaaS Prerequisites

      a. Recommended Hardware

      b. GTFS-RT Readiness

  1. Field Operations

      a. Ongoing Support

      b. Troubleshooting

          a.i. Troubleshooting Tablets

What is GRaaS?

GRaaS is a web app that creates GTFS-RT feeds using a variety of Android, iOS, and other internet-capable devices. This allows transit agencies to transmit their real-time vehicle positions and integrate them with different third-party applications that provide journey planning capabilities.

It is comprised of the following components:

  • Flask/Python server deployed to Google App engine
  • A library of Java tools
  • A web app for transit vehicles to post updates
  • On-board internet capable device

History of GRaaS

The California Integrated Travel Project (Cal-ITP) launched in 2019 with specific goals to improve public transport across the state and beyond. One of the main goals of the project was to provide accurate and complete information for trip planning in real-time in a way that gave transit agencies ownership over their own data: an end to black boxes. Cal-ITP looked to create an open-source software that created open data in an open standard. Thus, GRaaS was born.

GRaaS adds to the growing number of Mobility ‘as a Service’ projects in the transit sphere. The software creates real-time data in the General Transit Feed Standard (GTFS) format: vehicle positions and service alerts. (Note: At this time, we are not providing trip updates). We’re working to make transit data open and accessible for all.

As the industry standard, GTFS-RT feeds can be read by most journey planning apps like Google Maps, Apple Maps, TransitApp, etc. Before GRaaS, transit agencies could either pay specialized companies or simply not provide real-time information. We created GRaaS to change that.

GRaaS Prerequisites

Running GRaaS requires a dedicated internet-capable smartphone or tablet on each transit vehicle, and a good internet connection needs to be available to ensure higher quality data points.

Recommended Hardware

The team has also developed a hardware version of GRaaS (dubbed Babyshark) that is completely dedicated to transmitting GTFS data. This was developed as a solution to various issues that we found during our demonstrations using different tablets and smartphones such as screen timeouts, OS updates, and more.

You can still use GRaaS on other hardware such as tablets and smartphones. However, the following operational guidelines should be followed:

  • Use an internet-enabled device, not a WiFi-only device
  • Ensure that the device is connected to data, either via a SIM card or WIFI connection
  • Do not lock the device as it disrupts location data
  • Check that all software is up-to-date before running the app to eliminate any pop-ups which disrupt location services

The team has tested the following tablets and phones in the field and are confident in their ability to run the software:

  • iPad
  • Samsung Galaxy Tab
  • iPhone

GTFS-RT Readiness

The following table contains a list of items that are needed to facilitate the running of the GRaaS app. In some cases, the items are required to produce GTFS-RT.

Item GTFS-RT Use Case Requirements Associate check(s) in assessment process Description
A GTFS Schedule feed is published Required for GRaaS UI and prediction engine #1: GTFS Schedule Published A static GTFS feed must be created and hosted at a downloadable URL by the transit agency. This check is required to pass before all other checks can be completed.
The GTFS schedule feed is published at a permalink Required for GRaaS UI and prediction engine #2: GTFS schedule published at permalink Schedule data should be published publicly at a permalink (meaning a link that is stable and does not change) that the transit provider controls.
All required files within a static GTFS must exist Required for GRaaS UI and prediction engine Subset of #6: No critical validation errors The core files required to produce an MVP of a transit data schedule must be included in the GTFS feed. These include the following files:
  • agency.txt
  • stops.txt
  • routes.txt
  • trips.txt
  • stop_times.txt
  • calendar.txt and/or calendar_dates.txt
This item is able to be considered satisfied if the gtfs-validator does not include the error:
  • MissingRequiredFileNotice
Shapes included in GTFS Schedule Required for GRaaS Prediction engine #10: Valid shapes.txt published Although the shapes.txt file is listed as optional in the GTFS spec, it must be provided for the GRaaS prediction engine to work. This data may not be required by other GTFS Realtime prediction engines.
Referential integrity of the dataset is required Required for GRaaS UI and prediction engine Subset of #6: No critical validation errors All foreign keys in each record must refer to a defined record in the other appropriate table.
This item is able to be considered satisfied if the gtfs-validator does not include the errors:
  • DuplicateKeyNotice
  • ForeignKeyViolationNotice
Route/trip identifiers are required for all trips Required for GRaaS Driver UI Subset of #6: No critical validation errors Each trip in trips.txt must have one or both of the following:
  • A trip_headsign value
  • A route_short_name or route_long_name for the corresponding route
This item is able to be considered satisfied if the gtfs-validator does not include the errors:
  • RouteBothShortAndLongNameMissingNotice
Direction Identifiers are required Required for GRaaS Driver UI No check for this within assessment process The GTFS+ extension file of directions.txt is required for the GRaaS Driver UI. This may not required of other Realtime systems.
Each trip’s direction_id should have a correspond entry in the directions.txt file.
General integrity of underlying data is expected Required for GRaaS UI and prediction engine #6: No critical validation errors It is expected that there aren’t any major problems with the core data present within the static GTFS. As it pertains to the results of the gtfs-validator, if zero errors occur, it can be assumed that the data integrity is sufficient. It is technically possible that a GTFS Realtime system could function despite the presence of certain types of errors (particularly those that occur for fields that are not used by a GTFS-RT system), but those applicable errors may vary between each system. Some of these errors are also called out in other requirements of this doc.
Contents of the static GTFS data must be currently valid Required for GRaaS UI and prediction engine #14: Publish known changes to base schedule at least one week in advance The static GTFS must be valid for the current day of operation. This item is able to be considered satisfied if the gtfs-validator does not include the errors:
  • FeedExpirationDateNotice
    		•
    Contents of the static GTFS data must match current reality of operations Required for GRaaS UI and prediction engine #13: GTFS Grading Scheme Score The static GTFS must describe the current on-the-ground operational characteristics of the transit system. All elements of the core schedule and the shapes need to match the current reality of the transit system’s operations as best as possible.
    This particular check could be accomplished by someone manually completing a GTFS Grading Scheme assessment.

    Field Operations

    Once an agency has met the minimum requirements for running GRaaS, the team produces a unique QR code that can be read by a tablet or phone which sets up the GRaaS webapp with the agency's vehicles and routes. When onboarding a new agency, it is recommended that they are onboarded thoroughly to make sure that their drivers are running the app according to best practices. Each agency has a dashboard that is updated with daily trip reports which contain metadata on the trips made that day. This data includes the average lat/long update frequency, the vehicle number, trip ID, and other useful information.

    General recommendations in the case an agency already has the required hardware include:

    1. Confirm make/mode of devices.
    2. Make sure that device passcodes are on-hand prior to meeting with them.
    3. Make sure the tablet(s) are connected to a stable internet connection. If the 4G/LTE isn’t working well, try and get them connected to Wifi prior to meeting with them.
    4. Make sure location access is granted to the browser.
    5. Have Google Chrome installed on all Android devices in case it isn’t on some. Safari works well for iPads.
    6. Set Google Chrome as the default web browser on the tablet by going to Settings / Apps / Choose default apps / Browser app.
    7. Clear history/cache.
    8. Make sure that the person in charge of operations is attending the meeting. This is going to the point of contact who engages the drivers to walk them through the process of launching GRaaS.
             1. The agency should have the onboarding instructions readily available through print or on their monitor. The team        has shared their screen before during this process, but printing the instructions has always been the most        effective because of the QR code that needs to be scanned to sync an agency to their schedule.
    9. Emphasize the importance of having the browser running in the foreground with the screen on at all times. Since GRaaS is a webapp that uses location information, it cannot function while minimized. If that happens, location information will stop being transmitted and GRaaS will be paused.
    10. From the team's experience, a regularly scheduled power cycle (eg: every day or every week) is an important factor in consistently receiving higher quality updates. After keeping devices running for a few days, we have noticed that the update frequency goes down.

    Troubleshooting

    Other than software issues, GRaaS also relies on tablets and phones to run the webapp. This section was created to document the troubleshooting the team has had to do while working with California transit agencies.

    Troubleshooting Tablets

    Common issues with older tablets:
    Sometimes the camera does not work well and cannot catch the QR code during the onboarding process. There are a few things that you can try to get it to work, but some older models just won't pick up QR codes well.

    1. Make sure lighting is good.
    2. Make sure hand is steady.
    3. Make sure that the QR is printed or the screen is clear.
    4. Wipe the camera with a soft cloth.
    5. Reset camera settings to default.

    If a tablet is not giving lat/long updates:

    1. Make sure Google Chrome is set as the default browser on Android tablets and Safari on iPads. You can do this through the tablet/phone settings. Both Google Chrome and Safari have been tested through demonstrations and the team can't speak for the effectiveness of other browsers in running GRaaS.
    2. Try to connect to wifi and repeat. If this works, then the 4G/LTE connection might not be working, or is not good in that specific location.

    If the above options don't work, try the following:

    1. Power cycle the tablet.
    2. Try again, if still not working, clear cache / history and re-do the process.
    3. Try to use it in a different location with a working internet connection, ideally where there is a clear view of the sky. Sometimes the device GPS can be the problem.

    Single app mode for ipads

    Putting ipads into single app mode

    1. [Write me]

    Taking ipads out of single app mode

    1. Install Apple Configurator app on a mac
    2. Create credentials using credentials for ipad single app mode secure note in bitwarden, you will end up with a file called CalITP.organization
    3. Double-click file, enter password from secure note
    4. Connect ipad to mac with USB/lightning cable
    5. On the Configurator main screen, select the All Devices tab
    6. A large ipad icon should appear, with a copy of the ipad's home screen. If icon doesn't appear, disconnect device, wait a few seconds and reconnect. If icon still doesn't appear, reset ipad
    7. Right-click on icon, from the context menu choose Advanced->Stop Single App Mode
    8. Wait a few seconds for the mode change to take effect on the ipad
    9. Press Home button on ipad to get to main screen
    10. Done
    Clone this wiki locally