Car Park Finder - User Guide

By: Team T09-4 Since: Oct 2018 Licence: MIT

Table of Contents

1. Introduction
2. Quick Start
3. Features
Appendix A: FAQ
Appendix B: Glossary
Appendix C: Command Summary

1. Introduction

Welcome to the User Guide for Car Park Finder!

Car Park Finder is a desktop command-line application for all car owners seeking a hassle-free way to find Housing & Development Board (HDB) car parks in Singapore.

Our application allows you to view vital information such as parking lots availability for each car park, so that you can plan ahead of your trip.

If you use the computer frequently and commute by driving, why not give it a try. No installation is required and getting started is as simple as typing out a text message.

Interested? Read the next section on how to get started. If you already have Car Park Finder up and running then head on over to Section 3.

2. Quick Start

To get Car Park Finder up and running, just follow these simple steps.

2.1. Setup

Check that you have Java version 9 or later installed in your Computer.
Download the latest carparkfinder.jar here.
Copy the file to the folder you want to use as the home folder for Car Park Finder.
Double-click the file to start the application. The Graphical User Interface (GUI) should appear in a few seconds.

Figure 1. Home page of Car Park Finder

If everything goes well, Car Park Finder should launch immediately without any installation. Please refer to Figure 1 and check if it displays the same thing for you.

2.2. Graphical User Interface (GUI)

Figure 2. The six regions of the GUI

The GUI for Car Park Finder as shown in Figure 2 consist of six regions:

[1] Menu Bar [2] Result Panel [3] Google Map
[4] Message Box [5] Command Box [6] Status Bar

Please remember the naming convention as from now on they will be used to explain how Car Park Finder works.

Figure 3. Display of markers

There are two types of markers that is being used in Car Park Finder, as shown in Figure 3. You can click on a marker cluster to zoom in on the map, or click on a individual marker to view the car park details.

2.3. Enter a command

Type a command into the Command Box and then press Enter to execute it. A message will appear in the Message Box.

Some commands you can try:
query: Get the latest update from data.gov.sg
help: show the User Guide (this document)
list: display all the car parks

Congratulations, you have successfully executed your first command!

If you want to try out more, please refer to the next section or Appendix C.

3. Features

Welcome to the Features section. This is where you will be learning how to use every single feature in Car Park Finder. You will also learn the different types of errors that can happen and how to prevent them.

Command Format

Words in UPPER_CASE are the parameters to be supplied by the user.
For example, in find LOCATION, LOCATION is a parameter which can be used as find serangoon.
Parameters in square brackets are optional, and can be in any order.

If you find manually scrolling down to be a hassle, you can go back up to the table of contents and click on the individual features to go straight to them.

3.1. Viewing help : `help`

This command opens up the User Guide in a separate window and shows all the available commands. It also teaches you how to use them effectively.

If it is your first time reading this, then good job on opening the User Guide!

Format	Abbreviation
help	he / hel

Format

Abbreviation

help

he / hel

3.2. Querying data: `query`

On your first time running Car Park Finder, you will see nothing on your screen. Do not panic! By type query into the Command Box, it will start to fill the application with all the available HDB car parks.

Format	Abbreviation
query	q / qu / que / quer

Format

Abbreviation

query

q / qu / que / quer

If you wish to update all the car parks at a later date, just type this command again.
Remember that Car Park Finder does not automatically execute this command at the start.

3.2.1. Example: Let’s get some car parks!

It might be your first time using Car Park Finder, or you decided to clear out all the car parks. Whatever the case, its time to get some car parks into the application.

Message: Turning on notification
Loading… please wait…

Step 1. Type query into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly. Take note that you cannot type anything else once you press Enter.

Step 2. Wait for Car Park Finder to finish loading. It will only take awhile, so why not just sit back and relax?

Figure 4. Car Park Finder with 2099 car parks

Message: Finished loading
2099 car parks updated

Step 3. Once it has finish loading, the message above should appear. Please refer to Figure 4 to check if you are successful in getting the car parks.

3.2.2. Example: Query error(s)

Encountered a query error? Take a look below to see what went wrong.

Message: Query unable to retrieve car parks
Unable to retrieve car parks from data.gov.sg Please check your internet connection and try again

This error occurs when there is a connection problem to data.gov.sg. Please check your internet connection and try again.

3.3. Selecting a car park : `select`

You can either use this command to select a car park in the Display Panel, or just use your mouse to click on it.

There must be car parks available for you to select something.
If you have forgotten how to get car parks, please click here.

Format	Abbreviation	Example(s)
select INDEX	s / se / sel / sele / selec	select 1 s 2

Format

Abbreviation

Example(s)

select INDEX

s / se / sel / sele / selec

select 1
s 2

The index refers to the index number shown in the list of car parks in the Display Panel.
The index must be a positive integer 1, 2, 3, …
Selecting any index will automatically cause the Google Maps to zoom in on the car park location.

3.3.1. Example: Selecting the 20th car park in the list

This example will show you how to select a car park displayed in the Displayed Panel by using the command.

Figure 5. Selecting the 20th car park

Message: After selecting the 20th car park
Selected car park: 20

Type select 20 into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly. The selection will turn blue, as shown in Figure 5.

3.3.2. Example: Select error(s)

Encountered a select error? Take a look below to see what went wrong.

Message: Invalid command format
Invalid command format! select: Selects the car park identified by the index number used in the displayed car park list. Parameters: INDEX (must be a positive integer) Example: select 1

This error occurs when you type the command wrongly in the Command Box. Either try again or just copy the command here.

3.4. Listing all car parks : `list`

Show a list of all the car parks in the Display Panel with their various details. If there are no car parks to be displayed and you did not clear them, typing this command would bring it back.

Format	Abbreviation
list	l / li / lis

3.4.1. Example: Listing all the car parks

This example will show you know to list all the car parks again. It starts off with a smaller list containing only car parks in Hougang.

Figure 6. Previously filtered list, before using the list command.

From Figure 6, the current list only contains the car parks found in Hougang.

Figure 7. Listed 2099 all car parks

Message: Invalid command format
Listed all 2099 car parks

Type list into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly. Refer to Figure 7 to see if the command executed succesfully. All the car parks should appear in the Display Panel and the Google Maps should zoom out to show all of them.

3.5. Finding car parks : `find`

With a list of car parks, you can narrow down to just the car parks near your destination by either typing in the location or the specific car park number.

Format	Abbreviation	Example(s)
find KEYWORD	fin	find serangoon fin HG83

Format

Abbreviation

Example(s)

find KEYWORD

fin

find serangoon
fin HG83

Common words like BLK and AVE are ignored.
It does not matter whether the keywords are upper or lower case characters.

3.5.1. Example: How to find car parks by location

For this example, we will be looking at how to find all the car parks in Punggol.

Figure 8. Found car parks in Punggol

Message: Found 53 car parks
53 car park(s) found!

Type find punggol into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly. Figure 8 shows how it would look like, with the Google Maps zoomed in.

3.5.2. Example: How to find car park by car park number

Figure 9. Found car parks in Punggol

Message: Found 1 car park
1 car park(s) found!

Type find PP5 into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly. Figure 9 shows how it would look like, with the Google Maps zoomed in.

3.5.3. Example: Unable to find car park

If Car Park Finder is unable to find your location or car park number, it will display nothing.

Message: Found 0 car park
0 car park(s) found!

The message above will be shown, as well as an empty list in the Display Panel and no markers in the Google Maps.

3.6. Filtering car parks : `filter`

Filters the list of car parks returned by FindCommand by the following flags:

Car park has available parking slots a/
Car park has short-term parking s/
Type of car park ct/
Car park has free parking between a specified time period f/
Car park has night parking n/
Type of parking system that the car park uses ps/

FilterCommand can take in any number of flags, in any order.

Format	Abbreviation	Example(s)
filter FLAG&PARAMETER(S) [FLAG&PARAMETER(S)] …	fil, filt, filte	filter f/ sun 7.30am 5.30pm ct/ surface fil a/ ps/ coupon

Format

Abbreviation

Example(s)

filter FLAG&PARAMETER(S) [FLAG&PARAMETER(S)] …

fil, filt, filte

filter f/ sun 7.30am 5.30pm ct/ surface
fil a/ ps/ coupon

List of valid flags:

Criteria	Flag	Parameter Structure	Valid Parameters	Example(s)
Car park has free parking	f/	DAY START_TIME END_TIME	DAY: e.g. sun START_TIME: e.g. 7.30AM END_TIME: e.g. 9.30PM	filter f/ sun 9.00am 5.30pm
Car park has night parking	n/	-	-	filter n/
Type of car park	ct/	CAR_PARK_TYPE	surface, multistorey, basement, mechanised, covered	filter ct/ covered
Car park has available parking slot	a/	-	-	filter a/
Car park has short-term parking	s/	-	-	filter s/
Type of parking system	ps/	PARKING_SYSTEM_TYPE	coupon, electronic	filter ps/ coupon

Criteria

Flag

Parameter Structure

Valid Parameters

Example(s)

Car park has free parking

DAY START_TIME END_TIME

DAY: e.g. sun
START_TIME: e.g. 7.30AM
END_TIME: e.g. 9.30PM

filter f/ sun 9.00am 5.30pm

Car park has night parking

filter n/

Type of car park

ct/

CAR_PARK_TYPE

surface, multistorey, basement, mechanised, covered

filter ct/ covered

Car park has available parking slot

filter a/

Car park has short-term parking

filter s/

Type of parking system

ps/

PARKING_SYSTEM_TYPE

coupon, electronic

filter ps/ coupon

Take note that FindCommand must be used to find a list of carparks within the location first.

Upper or lower case characters do not matter.

Figure 10. Filtering surface car parks that have available parking lots and night parking.

3.7. Undoing commands: `undo`

Restores the list of car parks to the state before the previous undoable command was executed.

Format	Abbreviation
undo	u / un / und

Only available for the following undoable commands:
query | find | filter | notify | clear

This does not turn off notification as it only affects the list of car parks.

3.7.1. Example: Successful undo

If you accidentally type an undoable command and wish to undo it, here is how.

Message: Success in undoing
Undo success!

Type undo into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly.

3.7.2. Example: Unable to undo

Not all commands are undoable as there is a limit to the number of undo commands.

Message: Success in undoing
No more commands to undo!

If you see the message above in the Command Box it means there are no more undoable commands. You can also check the history to view what commands you have typed in so far.

3.8. Redoing commands : `redo`

Reverse the most recent undo command.

Format	Abbreviation
redo	r / re / red

You can only redo after an undo command.

Like undo, this does not turn off notification as it only affects the list of car parks.
Redoable commands are the same as undoable commands.

3.8.1. Example: Successful redo

If you decided to redo the undo command, here is how.

Message: Success in redoing
Redo success!

Type redo into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly.

3.8.2. Example: Unable to redo

You reach the end of how far you can redo. Take note that not all commands are undoable / redoable.

Message: Success in redoing
No more commands to redo!

If you see the message above in the Command Box it means there are no more redoable commands. You can also check the history to view what commands you have typed in so far.

3.9. Calculating the cost of parking : `calculate`

Calculates the cost of parking at a selected car park between a specified time period.

Format	Abbreviation	Example(s)
calculate CARPARK_NAME DAY START_TIME END_TIME	ca, cal, calc, calcu calcul, calcula, calculat	calculate TJ39 sun 3.30am 6.30pm ca TJ39 sun 3.30am 6.30pm

Format

Abbreviation

Example(s)

calculate CARPARK_NAME DAY START_TIME END_TIME

ca, cal, calc, calcu
calcul, calcula, calculat

calculate TJ39 sun 3.30am 6.30pm
ca TJ39 sun 3.30am 6.30pm

CalculateCommand takes into account the free parking times of car parks. It returns an error message if the car park has no short-term parking.

Figure 11. Calculating the cost of parking at car park Y14 on Monday from 9.00am to 5.30pm

3.10. Enabling Notification : `notify`

Enabling notification requires you to have already selected a car park.
If you have not done so, please look at how to find car parks by location and filter them through the use of flags.
Also, click here if you have forgotten how to use the query command to get a list of car parks.

After selecting a car park, you can choose to receive notifications on how many parking lots are still available. It sends an update periodically, so once it is enabled you do not need to type the command again into the Command Box.

Format	Abbreviation	Example(s)
notify TIME_SECONDS	n / no / not / noti / notif	notify 0 notify 10

Format

Abbreviation

Example(s)

notify TIME_SECONDS

n / no / not / noti / notif

notify 0
notify 10

If you did not select a car park beforehand, Car Park Finder would not know which car park needs to be updated.
You can set within a range of 10 to 600 seconds (10 minutes). Decimal values are not allowed.
Typing query or clear will disable the notification.
As notify is based on the index of select, you can select another car park to receive notification while it is enabled.
This means if you type find hougang and the original car park is gone but the index is still valid, it will update that car park instead.

3.10.1. Example: Receive notification every 10 seconds

This example assumes you have already decided on a car park. For more information on how you can choose a suitable car park in Car Park Finder, please click here.

It is time to head to your destination. Before you do so, why not check if the car park is full?

Figure 12. Selected Car Park AM18

Step 1. Select your car park from the list. In this example, we will choose the 5th car park as shown in Figure 12.

Message: Turning on notification
Notification enabled for car park AM18 Interval: every 10 seconds

Step 2. Type notify 10 into the Command Box. The message above should appear in the Message Box as confirmation that you typed in correctly.

Figure 13. Before and after receiving notification

Message: Notification with no change in lot(s) available
Car park AM18 has 159 lot(s) available Interval: every 10 seconds

Message: Notification with lot(s) freed
Car park AM18 has 167 lot(s) available 8 lot(s) freed since last check Interval: every 10 seconds

Message: Notification with lot(s) taken
Car park AM18 has 152 lot(s) available 7 lot(s) taken since last check Interval: every 10 seconds

Step 3. Now that the notification is enabled, you do not have to do anything else. It will inform you whether there is a change in parking lots availability through visual updates like these messages above and Figure 13.

3.10.2. Example: Turn off notification

Now that you have gotten tired of the notification, it is time to disable it.

Message: Turning off notification
Notification disabled

The message above will be displayed when you type notify 0 into the Command Box. You can also exit Car Park Finder to turn off notifications.

Message: Already disabled
Notification already disabled

If you are unsure whether you have already disabled the notification, the message above will be shown if you have done so.

3.10.3. Example: Notify error(s)

Encountered a notify error? Take a look below to see what went wrong.

Message: Invalid command format
Invalid command format! notify: Set when to receive notification about the lot availability of a car park. Parameters: SECONDS 0 to disable, range is 10 to 600 seconds (decimals not allowed) Example: notify 10

This error occurs when you type the command wrongly in the Command Box. Either try again or just copy the command here.

Remember that notify 0 is how you disable the notification.

Message: Notification without selecting a car park first
Cannot notify without selecting a car park first

This error occurs when you did not select a car park and tried to enable notification. Please click here for more information.

Message: No car park data found
Unable to retrieve car park information from data.gov.sg Unfortunately, the data is not available. We apologise for any inconvenience caused

This error occurs when the data is not available from data.gov.sg. Therefore, it is not possible to enable notification for that particular car park.

Message: Notification unable to retrieve car parks
Unable to retrieve car parks from data.gov.sg Please check your internet connection and try again

This error occurs when there is a connection problem to data.gov.sg. Please check your internet connection and try again.

3.11. Clearing all entries : `clear`

If you want to clear out all the car parks in Car Park Finder, this is the command for you.

Format	Abbreviation
clear	cl , cle, clea

Format

Abbreviation

clear

cl , cle, clea

3.11.1. Example: Clear all car parks

Message: Clear all car parks
All car park information has been cleared!

Once all the car parks are cleared, the message above will be displayed in the Message Box.

3.11.2. Example: No car parks

Message: No car parks to be cleared
There is nothing to be cleared.

If Car Park Finder does not have any car parks, then it will show the above message.

3.12. View past commands : `history`

Show all the commands that you have entered in reverse chronological order.

Format	Abbreviation
history	hi , his , hist , histo , histor

Format

Abbreviation

history

hi , his , hist , histo , histor

Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.
Using the mouse is not considered a command, so clicking on a car park will not be recorded.

3.12.1. Example: Checking history

After running several commands, you might have forgotten what you have type in previously into the Command Box.

Message: List of commands
Entered commands (from most recent to earliest): s 19 find punggol q clear help list

Type history into the Command Box. The message above is an example, but it should appear similar to the message in the Message Box as confirmation that you typed in correctly.

3.12.2. Example: No past commands

If there are no previous commands, then they will be nothing to show. Remember that using the mouse to click is not considered as a command.

Message: No commands found
You have not entered any commands yet

The message above will show when you run Car Park Finder and type history into the Command Box, without typing any other commands first.

3.13. Abbreviation: abbrev.

If you find the command words too long to type. Guess what? We have executable short form for each command in our command list.

You can find abbreviations of each command in the table that we provide to each section from 3.1 to 3.19.

However, there are ambiguous abbreviations that are not distinguishable between multiple commands. Thus, you CANNOT use them: c, f, fi, h.

To see how useful it can be, please take a look at the examples below.

3.13.1. Example: Calculate Command

Step 1. Instead of entering calculate into the Command Box, you can enter ca instead.

Step 2. complete the rest of the fields with TJ39 SUN 7.00AM 9.00PM, followed by pressing Enter to execute.

3.14. Autocomplete: `Tab`

If you forgotten how to type a command, do not worry! By typing in the first letter of the command in the Command Box and pressing the Tab key, it will display the full format of the command.

Only available for the following commands:
select | find | filter | notify | calculate

To see how useful it can be, please take a look at the examples below.

3.14.1. Example: Select Command

Step 1. Enter s into the Command Box, followed by pressing Tab. Your select command will be completed.

Step 2. Substitute the selected field INDEX with 1, followed by pressing Enter to execute.

3.14.2. Example: Filter Command

Step 1. Enter fil into the Command Box, followed by pressing Tab. Your filter command will be completed.

Step 2. Substitute the selected field DAY with SUN, followed by pressing Tab to move to the next field.

Step 3. Repeat step 2 until you substitute all the fields with actual value. (You can remove those fields you choose not to use). Then press Enter to execute.

3.15. Exiting the application : `exit`

When you are done with Car Park Finder, type this command to exit the application. You can also click on the close button above the menu bar to exit.

Format	Abbreviation
exit	e / ex / exi

Before Car Park Finder stops running, it saves a local copy of all the car parks in the list.
When you start the application again, it will load up the local copy.

3.16. Adding to favorites list : `add` `[coming in v2.0]`

Add a car park into your favorites list.

Format

Abbreviation

Example(s)

add c/CARPARK_NUMBER

a / ad

add c/SE12

3.17. Removing from favorites list : `delete` `[coming in v2.0]`

Remove the specified car park from your favorites list.

Format

Abbreviation

Example(s)

delete c/CARPARK_NUMBER

d / de / del / dele / delet

delete c/SE12

3.18. Sorting car parks : `sort` `[coming in v2.0]`

Sort the list of car parks by distance or name.

To sort all the car parks, you must list them first!

Format

Abbreviation

Example(s)

sort TYPE

so / sor

so NAME

3.19. Weather forecast : `weather` `[coming in v2.0]`

Include weather updates in the notifications by indicating on or off.

Format

Abbreviation

Example(s)

weather TOGGLE

w / we / wea / weat / weath / weathe

weather on
weather off

Appendix A: FAQ

Q: How do I transfer my data to another computer?
A: Install the application in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous Car Park Finder folder.

Q: If I do not know the postal code of the location, am I still able to find car parks through other means?
A: Yes, by typing keywords like street names.

Q: How much do I need to pay for the application?
A: It is totally free! Head over to our releases page to try it out!

Q: Does car park finder harm the environment?
A: No! It reduces the amount of cars on the road by reducing the waiting time for car parks!

Q: How do you plan to earn money in the future?
A: We plan to serve you deals on the best deals based off your selected car park!

Q: What future expansions do you see in the future?
A: We plan on listing hawker centers and have a real time CCTV feed of the entrance of the car park.

Appendix B: Glossary

Unsure of a few technical terms? We got you covered. Refer to Table 1 below.

Table 1. Technical Terms
Term	Explanation
Autocomplete	Provides suggestions while you type into the field.
Favourites	A custom list of car parks that is meant to be viewed easily.
Flag	Flag is a value that acts as a check for the filter feature.
Google Maps	It is a online map service provided by Google.
Mainstream Operating System (OS)	Windows, Linux, Unix and OS-X are operating systems used widely in the world.
Marker	This is should in the Google Maps to indicate the location of the car park. You can click on it to either zoom in or display more information.
User Interface (UI)	Allows the user to interact with the application through inputs and outputs of data.

Appendix C: Command Summary

This is the last section of the User Guide, but the most useful if you just want a list of commands to try. Refer to Table 2 for general commands and Table 3 for car park management. For more details on what each command does, please refer to Section 3.

Table 2. General Commands
Command	Format	Example
Help	help	he
List	list	l
Undo	undo	u
Redo	redo	r
Clear	clear	cl
History	history	hi
Exit	exit	e

Table 3. Car Park Management
Command	Format	Example
Query	query	q
Select	select INDEX	s 2
Find	find KEYWORD [MORE_KEYWORDS]	fin punggol
Filter	filter FLAG/ PARAMETER [MORE_FLAG/ PARAMETER]	fil f/ SUN 7.30AM 5.30PM ct/ SURFACE
Calculate	calculate DAY START_TIME END_TIME	cal SUN 3.30PM 6.30PM
Notify	notify TIME_SECONDS	n 60