User stories

pasco Repository

This is the home to the project. Please fork and make changes on this project going forward.

Simple Pull Requests

Before we get into the full-blown "proper" way to do a pull request, let's quickly cover an easier method you can use for small fixes. This way is especailly useful for fixing quick typos in the docs, but is not as safe for code changes since it bypasses validation and linting.

1. Sign in to GitHub

3. Click the pencil icon to "Edit this file"

4. Make any changes

5. Describe and submit your changes within "Propose file change"

That's it! GitHub will create a fork of the project for you and submit the change to a new branch in that fork. Just remember to submit separate pull requests when solving different problems.

Proper Pull Requests

We like to keep a tight flow when working with GitHub to make sure we have a clear history and accountability of what changes were made and when. Working with Git, and especially the GitHub specific features like forking and creating pull requests, can be quite daunting for new users.

To help you out in your Git(Hub) adventures, we've put together the (fairly standard) flow of contributing to an open source repo.

Forking the repo

Whether you're working on the API or the App, you will need to have your own copy of the codebase to work on. Head to the repo of the project you want to help out with and hit the Fork button. This will create a full copy of the whole project for you on your own account.

To work on this copy, you can install the project locally according to the normal installation instructions, substituting the name acecentre with the name of your github account.

Keeping your fork up to date

If you're doing more work than just a tiny fix, it's a good idea to keep your fork up to date with the "live" or upstream repo. This is the main acecentre repo that contains the latest code. If you don't keep your fork up to date with the upstream one, you'll run into conflicts pretty fast. These conflicts will arise when you made a change in a file that changed in the upstream repo in the meantime.

On git remotes

When using git on the command line, you often pull and push to origin. You might have seen this term in certain commands, like

git push origin master

or

git pull origin new-feature

In this case, the word origin is refered to as a remote. It's basically nothing more than a name for the full git url you cloned the project from:

git push origin master

is equal to

git push git@github.com:username/repo.git master

A local git repo can have multiple remotes. While it's not very common to push your code to multiple repo's, it's very useful when working on open source projects. It allows you to add the upstream repo as another remote, making it possible to fetch the latest changes straight into your local project.

# Add 'upstream' to remotes
git remote add upstream git@github.com:acecentre/pasco.git

When you want to update your fork with the latest changes from the upstream project, you first have to fetch all the (new) branches and commits by running

git fetch upstream

When all the changes are fetched, you can checkout the branch you want to update and merge in the changes.

git checkout master
git rebase upstream/master

If you haven't made any commits on the branch you're updating, git will update your branch without complaints. If you have created commits in the meantime, git will step by step apply all the commits from upstream and try to add in the commit you made in the meantime. It is very plausible that conflicts arise at this stage. When you've changed something that also changed on the upstream, git requires you to resolve the conflict yourself before being able to move on.

Conflicts You should always favor changes on upstream over your local ones.

Doing Work

Whenever you begin working on a bugfix or new feature, make sure to create a new branch. This makes sure that your changes are organized and separated from the master branch, so you can submit and manage your pull requests for separate fixes/features more easily.

# Checkout the master branch - you want your new branch to come from master
git checkout master

# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature

# Switch to your new branch
git checkout newfeature

Up-to-date Make sure to update your master branch with the one from upstream, so you're certain you start with the latest version of the project!

Submitting a Pull Request

Prior to opening your pull request, you might want to update your branch a final time, so it can immediately be merged into the master branch of upstream.

# Fetch upstream master and merge with your repo's master branch
git fetch upstream
git checkout master
git merge upstream/master

# If there were any new commits, rebase your master branch
git checkout newfeature
git rebase master

Make sure to check if your branch is up to date with the master branch of upstream. An outdated branch makes it near impossible for the maintainers of acecentre to check and review the pull request and will most likely result in a delayed merge.

Once you've commited and pushed all the changes on your branch to your fork on GitHub, head over to GitHub, select your branch and hit the pull request button.

You can still push new commits to a pull request that already has been opened. This way, you can fix certain comments reviewers might have left.

Please allow the maintainers of upstream to push commits to your fork by leaving the "Allow edits from maintainers" option turned on. This allows our Core Team to help out in your PR! :::

Feature Requests

80/20 Rule

The main thing to be aware of when submitting a new acecentre feature request, is our rule on edge-cases. To keep the acecentre core codebase as clean and simple as possible we will only consider adding features that at least 80% of our user-base will use. If we feel that less than 80% of our users will find the feature valuable then we will not implement it. Instead, those edge-case features should be added as Extensions.

Browsing Existing Requests

Also, if you want to see the most highly requested features you can sort by :+1: (the thumbs-up emoji).

Submitting a Request

If your idea passes the 80/20 test and has not already been submitted, then we'd love to hear it! Submit a new issue using the Feature Request template and be sure to include the enhancement label. It's important to completely fill our the template with as much useful information as possible so that we can properly review your request. If you have screenshots, designs, code samples, or any other helpful assets be sure to include those too!

Voting on Requests

You can also vote on existing feature requests. As mentioned above, the :+1: and :-1: are used for sorting, so adding one of these reactions to the GitHub issue will cast a vote that helps us better identify the most desired (or undesired) features. And remember to add a comment if you have additional thoughts to help clarify or improve the request.

Fulfilling a Request

Our core team is always working hard to implement the most highly-requested community features, but we're a small team. If you need the feature faster than we can provide it, or simply want to help improve the acecentre platform, we'd love to receive a pull-request from you!

Quick Edit method

Editing

1. Tap on the edit button

1. Using the navigation menu - navigate to the node you want to edit

Tap the down arrow to go down, the right arrow to go into a sub tree element for example

1. Edit the text in the node.

Note that if you put text in brackets after the word - this will be the cue text. Other text is read out loud as the main text. For example My care (care) will have the cue of care and read outloud My care

1. Hit the Save button (top right) when done.

Here is a quick video demonstrating this:

Adding and removing elements

1. Tap on the edit button

1. Using the navigation menu - navigate to the part where you want to add a new element - or list of elements

So tap down to go down - right - to go into a sub tree element.

1. Use the Green Plus or Red Minus icons to add or remove elements

So pressing a plus above the selected element will add a new element above, pressing it below will add an item below - and right - will add a new sub-element.

Equally removing an item is easy by pressing the delete button.

There is no revert or undo! Be careful with the delete tool!

1. Hit save when done

Here is a quick video demonstrating this:

Adding or removing audio recordings

With the quick edit mode you can also add or remove audio recordings. Pasco is unique in that you can have an audio recording for the cue - and main item.

Text file - in settings method

For example. This is a standard layout:

- My phrases
	- Hello
	- Goodbye
	- Thanks
	- No thanks
	- Questions
		- How are you?
		- What are you doing today?

and you don't need to use - dashes if you don't wish e.g.

My phrases
	Hello
	Goodbye
	Thanks
	No thanks
	Questions
		How are you?
		What are you doing today?

ATX formats use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example this is the same vocabulary file using ATX style headings:

# My phrases

## Hello

## Goodbye

## Thanks

## No thanks

## Questions

### How are you?

### What are you doing today?

Background on the markdown format we use

As well as the basic format - we use some basic formatting tricks:

• Cue message. The main message is the first item. The cue is anything in brackets. e.g. My phrases (phrases) will say "My Phrases" out loud but give the cue as "phrases"

You can either edit the text file directly in the app (go to Settings -> Vocabulary -> Edit Tree) - or in a seperate text file app and then paste it into this text area. A video demonstrating the two approaches is seen below.

Importing from other AAC programs

Access

On-Screen Navigation

Access Mode

There are currently three options;

1. 1 switch - Auto-Scan

2. 2+ switches

3. Wheel (NB: Experimental!)

Switch Setup - Background

2+ Switches (Default)

By default switch access is set to Manual - which would allow someone to use the on-screen navigation tool - or use 4 switches to navigate the currently active language tree. For example the arrow keys - up, down, left & right - would allow someone to access the tree. Equally, the keys a (left), s (down), d (right), w (up) can be used. Lastly the keys 1 and 2 would allow a user to go left and right in the tree.

1 switch - Auto-Scan

Automatic scanning, often called "1 switch scanning" allows a user with one switch to navigate pasco. The computer moves through each item so the user doesn't have to - and only selects the one they want when ready.

Be aware - you need to select which switch key selects (moves forward) - which you can do in the option "Switch key to select items". There are then some options you can configure:

Loops (Default: 3)

The number of times the automatic scan runs through each level of the tree before stopping.

Delay at first item (ms) (Default: 1000 ms)

It is sometimes useful to have a delay at the first item in each level of the branch to help someone to time their switch press.

Auto-scanning delay (ms) (Default: 3000 ms)

The time the scanner moves from one item to a next automatically. Want it to scan quicker/faster? Move it down. Want it to scan slower? Move it up.

Configure Actions

Switch key to select items

Here you can choose your switches (keys) and what should do what action. Select the action (e.g. in Automatic/1-switch scanning you will need to just select the "Select item" action). Then add your key. Remove any keypresses that you don't want to be used by pressing the red cross.

Minimum Cue Time (ms) (Default: 0 ms)

By turning this on it stops the user selecting a large number of items in the tree before hearing the cue. You can change the default time here.

You probably want to keep it under 500ms other wise it can feel laggy

Ignore second hits (ms) (Default: 100 ms)

This feature stops the switches being responded to if they are hit within this timeframe. So for example, if a user presses a switch and hits immediately afterwards - pasco will ignore this second press if it is within the timeframe. Some

Helpers

We will add additional 'helpers' (actions that alter the tree) here - but for now we only have one helper:

Back option for all branches

It's really useful for single switch scanners to get back a branch if they need to. This adds the option of 'Back' to the end of each Branch, at the beginning of each branch or not at all.

Speech

Cue Voice

The cue voice - often called the private voice is the synthesised voice that is designed for the communication user to hear. Ideally this would be to a headphone or quiet speaker that only the communication aid user can hear.

Choose your voice and the related volume, pitch and rate (speed) of the voice as you wish. Note there is a plus symbol - this allows people who are using more than one language to add a different synthesised voice for that language. Note there is a line on each slider. This defines the default position so you can reset it if you ever slide this by accident.

Main Voice

The main voice - often called the public voice is the synthesised voice that is designed for the communication partner(s) to hear. This is often an amplified speaker.

Choose your voice and the related volume, pitch and rate (speed) of the voice as you wish. Note there is a plus symbol - this allows people who are using more than one language to add a different synthesised voice for that language.

First time run (Cue Voice)

For many people who are visually impaired its useful to 'hear' the items at each selected branch. This is like someone who is using their eyes to visually scan the interface. It give the user a fast way of scanning the items. If you turn this on we recommend making as fast as you can before the voice becomes hard to understand.

This won't increase the speed of any recorded messages. Note: This option is only available for automatic scanning.

Appearance

This area defines how the application looks and feels.

Font size

Adjust the font size of the text shown in pasco

Theme

There are a number of themes - some designed for people with a visual impairment - to aid easier reading of the text

Locale

To change the language of the app (the menus and the configuration text) you can change it here.

This doesn't automatically change the language of the trees/vocabulary. For that you will have to use something like google translate.

Vocabulary

Active Tree

Tools

Load an example tree

Pasco has some example vocabularies installed which you can load up. Select the tree, Press "load selected"", then "Save Tree".

Export / Import

Here you can export or import your vocabulary file as a zip file - or a OBF file - to be used in different AAC programmes.

Edit Tree

Below are solutions to some common issues that you may experience when working with pasco.

Sound issues

I have a bluetooth speaker connected but its coming out the device (or vice versa)

Its fair to say we haven't nailed bluetooth speakers yet. Its tough

Editing issues

How do I get the keyboard to edit text?

Press and hold the small arrow in the bottom right of the keyboard.

But I can't enter a tab! How do I do it?

Yes. Annoyingly there is no tab key on iPads/iPhones etc. So what to do? Follow these steps to make a keyboard replacement

These Docs will help get you up-and-running quickly, guide you through advanced features, and explain the concepts that make pasco so unique.

What is pasco?

pasco is an open-source unique communication solution aimed at individuals who have a physical and visual impairment.

A quick overview

What makes it unique?

Note we definitely aren't trying to make something that already exists. There are many solutions those less visually impaired or with greater physical access can use - and should use! However if you want a purely auditory scanning interface you may want some features that these options struggle to provide as they try and meet the needs of a greater selection of indviduals. So what can we provide in pasco for auditory scanning?

• Lets imagine you want a auditory cue in one language - but output your main "voice" in another. Thats difficult to do right now in many commercial solutions

• If you want rapid 'pre' auditory scan - a auditory cue that is like quickly visually scanning the interface in front of you

• You want a recorded audio file (e.g. someones actual voice) for the main spoken output - and a different recorded audio file for the cue.

• Because the language file doesnt have pictures why can't you just write out somones list of phrases and messages in a text file?

• you want a way of scanning in-app in a special way - but be able to use the entire device too - not just in a really slow in-efficient way that is great for all other apps - but not communication.

• as well as simple text files wouldnt it be great to import and export to different communication apps? After all, your language is yours not a software companies.

There are three formats that pasco reads langauge trees in.

1. Mindnode - Markdown format. - ATX Style

Files look a little like this:

# Chat


## How are you?

- Ace!

- Whats that?

- 

## Whats happening?

- Yeah for sure

## I’m fed up


# I need something


## Its in my bag

## Its somewhere else

## Its upstairs

It's not the easiest to read - note that with markdown line breaks are key. It's easiest to generate this with something like MindNode - an iOS and Mac app to generate MindMaps. It really is a breeze

1. Tab OR Space Indented text file

Here a file looks like this:

Chat
	How are you?
	Ace!
	Whats that?
	Whats happening?
		Yeah for sure
	I’m fed up

I need something
	Its in my bag
	Its somewhere else
	Its upstairs

It looks a little easier to read - but be warned - spaces and tabs at the beginning cannot be mixed. Don't put a space and then a tab. Its not the easiest.

1. Open Board format

To export - select Export in the Configuration screen and select 'obz' format. You will need a way of sharing this file - either via email or your files app (and then dropbox etc) to make use of this outside of your iPad. Note it exports all your sound files too.

Configurations for different use cases

A Single Switch user

• Loops. This is how many times the scan will go through each level of the tree if no item is selected. It can be useful if the indvidual wants to listen first and then select. However if you are using it for this try and look at the "First time run" Option

• Delay at first item. Sometimes its difficult for people who use auto-scanning to select start the scan AND select the first item. This delay time adds an extra delay to the very first item at each level of the vocabulary

• Auto-scanning delay. This is the time it takes to move from one item to the next. Some people call this the "Scan Time".

There are some other settings too which are not specific to single switch scanning:

• Switch key to select items Many switch boxes (the piece of equipment that connects your switch to the computer) use space or enter as the emulated key press. Which emulated key press are you using? This will be the key that selects items

• First Time Run (Cue Voice) It can be useful to have a cue for the first time the scan goes through each level of your vocabulary. This may go a lot faster than the regular scan rate. This is called the First time Run. By turning this on you can change the rate and a different voice if required

• Ignore second hits(ms) If the user has difficulty pressing the switch once - or for example tremors on a switch - increasing this time can help. It ignores second hits of the switch if they are within the time period selected

• Ignore key presses under n ms This setting tells the app to ignore short switch presses. You can alter this time as you need to.

One last configuration that is very helpful for automatic scanning is the "Back option for all branches" Under Helpers. This puts a "Back" action at the bottom of each level of the vocabulary allowing someone with one switch to go back a branch if they make a mistake.

A Two-Switch user

Some people may use two switches. One switch will move through the items - with a second switch selecting them. This is called Two-switch or Manual scanning. To configure pasco for this within the Config Screen change it to "Manual" Under "Switch Access". There are some options available when you do this.

• Switch key to select items Many switch boxes (the piece of equipment that connects your switch to the computer) use space or enter as the emulated key press. Which emulated key press are you using? This will be the key that selects items.

• **Move with the other switch (Step scanning)**You will need to select this if you are using two switch scanning. What does this button do? Lets imagine you select "Space" as your selection key. Checking this box will make "Enter" your move key. Equally if you have "Enter" as your selection key it makes "Space" the move key.

• First Time Run (Cue Voice) It can be useful to have a cue for the first time the scan goes through each level of your vocabulary. This may go a lot faster than the regular scan rate. This is called the First time Run. By turning this on you can change the rate and a different voice if required

• Ignore second hits(ms) If the user has difficulty pressing the switch once - or for example tremors on a switch - increasing this time can help. It ignores second hits of the switch if they are within the time period selected

• Ignore key presses under n ms This setting tells the app to ignore short switch presses. You can alter this time as you need to.

One last configuration that is very helpful for manual scanning is the "Back option for all branches" Under Helpers. This puts a "Back" action at the bottom of each level of the vocabulary allowing someone with one switch to go back a branch if they make a mistake. NB: If someone can access a third switch you can set this switch to "A" or "Back arrow".

Someone who controls the up/down keys on a remote control

Some individuals can operate one finger or thumb with some dexterity once positioned in the correct place so that they, for example, can control the navigation arrows of a remote control. Pasco has a built in navigation aid that, although designed for a communication partner to use can be useful for the individual. To turn this on Select the "On" option of the "On-screen navigation".

The navigation arrow allows you to go up,down, left and right through the language of your vocabulary

Once on you can press and hold on the 4 way arrow to move the navigation tool around the screen to where you need it - and resize it. To resize it press and hold on the middle of the arrow then grab the edge of the dotted line surrounding it to resize the tool.

Someone who can control the arrow keys of a external (Bluetooth or wired) keyboard

To use this, pair with your device (iPhone, iPad or other device using pasco). Make sure your numlock setting is on so you can use the arrow keys. The arrows allows you to go up,down, left and right through the language of your vocabulary

A non-native Communicator

Some people may understand one language but need to communicate to others in a different language. Pasco allows you to do this by changing the voice of the cue (the voice that the pasco user would hear) - and the main voice (the voice that others would hear). There are two ways you can achieve this with pasco

1. Using the in-built Text to speech engine - and changing the language

2. Recording your own cue/main voice audio recordings

Editing

pasco has some simple and advanced editing available. We will first look at the simple - within app way of editing. To Edit within the app navigate to the tree or part of the tree you want to access (hint: enabling the navigation tool helps this) and then hit the Top right Edit icon (looks a little like a pencil and pad). Once in this mode tap on the item you want to edit. A white box will appear with small markers. If you want to edit the text (the label) - just tap in the white area and with the on-screen keyboard edit the text as you wish.

If you want to add a new item above or below this item - simply hit the plus symbol either above or below the item

If you want to change the recorded cue or main recording - you can do this by tapping on the spanner symbol next to the item you want to change. Then in the next window select which the recording is for (Main, Cue or Both) and press and hold the red "Record" button. Release the button when you are finished recording.

Advanced editing

In the config it's possible to import and export your own language tree. This is simply a text file. There are two ways you can make this:

Copy and paste the file (either the markdown file - or the indented text file) into the Tree in the Config.

1. Bi-Lingual. Small Thumb movement in 4 directions

Said is a 45-year-old man who lives at home with his wife. Said and his wife are Kurdish and have lived in the UK for 10 years.. Said speaks and understands English, his wife has limited English and speaks to Said in Kurdish. He has Motor Neurone Disease which has now affected his speech to the point others can no longer understand him. His eyesight is poor. He still operates a TV remote by holding the remote between his thumb and forefinger – but can only operate the 4 way TV controls. He wants to spell out whole words and communicate his care needs with carers. He has tried eyegaze technology in the past but this has not been successful.

1. Bi-lingual. High-Contrast requirements

Fen is a 56-year-old woman who lives in the UK, she is a first-generation immigrant from China. She has had a brainstem stroke limiting her physical skills to a small thumb movement. It is not clear what Fen can see – her family and care staff feel she can hear better than she can see. Prior to her accident she spoke and understood verbal Chinese (Mandarin) well with her family members. Fen now lives in a care home where staff are English speaking. Fen would like to make her care needs known to staff and her family would like to communicate further with her. Fen has begun to use a partner assisted auditory scanning system using a paper-based book put together with her family. As this system is in Chinese it is not accessible to care staff.

1. English speaking child with developing vocabulary

Joel is a 6-year-old boy who has a significant visual impairment and physical difficulties. He lives at home with his Mum, Dad, baby brother and dog. His family speak both Portuguese and English. He has trialled some AAC by auditory fishing (dragging his hand across a device and hearing a cue about what is underneath it) and selecting with a switch – but this has proven difficult. He can activate a switch well with his head. He has begun to use a partner assisted scanning book with his mother e.g to choose activities to play with; to make comments like telling his mum he loves her.

It takes significant resources to maintain and advance pasco. If you'd like to help keep pasco active and open-source please consider supporting it through one of the methods below.

Financial Support

Our development and research all cost money. If you can spare the cash, we have a few ways to help us keep the lights on.

Memberships

We accept memberships through our Patreon account. These monthly donations are the ideal financial contribution since they're a bit more dependable and we can roughly predict the monthly amount. (not yet released)

One-Time Donations

Pull Requests

Docs

Translations

Bug Reporting

This one is surprisingly underutilized. If you encounter a bug within pasco, no matter how small, we would love to hear about it. With such a small team, it's difficult for us to test every commit. Sometimes after we update a small snippet of code, a totally different piece of code breaks elsewhere. More people using and testing the software is always good, but if no one reports the issues they come across then it may not get fixed!

Social Posts

Testimonials

pasco is very much in-development. Its largely being provided by Ace Centre staff for the purposes of named individuals. If you start using pasco and need more support follow the below options

Email

Slack

Auditory First

AAC for Auditory and Physically impaired first. Other solutions exist for other purposes. pasco is not a tool to meet all needs

Flexible and powerful configuration

Need a cue in one language and main voice in another? Need recorded sounds and voices for the cue and different ones for the main? Need next letter word prediction? pasco has you covered for features not available elsewhere

Here to help

COMPATIBILITY NOTE pasco is working best on iOS right now. Other platforms to follow.

pasco is designed to work well with an external headphone or speaker so the person communicating can only hear the cue rather than others in their environment hearing the cue constantly. Please note. This feature is only available on iOS at present. To do this plug in a wired headphone or speaker to the device (it does not work on bluetooth speakers yet!). When you do this all sound, by default, will now be directed to your headphones. To redirect the Main voice to the speaker of the iPhone/iPad you need to check the box to redirect the output in the Config->Speech.

Bluetooth

Wired

So pasco is unique because we have thought about early switch scanners - and seasoned switch scanners from the start of development. The problem for many switch scanning users is they either learn to use a easy approach within a specific app - but usually the user is then stuck within the app; or they have to use the built-in iOS switch scanning which is often inefficient when using it for communication because you have to scan through screen elements and actions that you don't need access to.

In pasco you can either use our built-in scanning methods - or use the ios scanning method. How? Well to use the iOS scanning method we recommend setting up a switch recipe which "hold at point". With one switch - create the recipe by tapping at the point of the right arrow of the navigation menu. Put a timeout on the recipe - and this will allow the user to go back to normal scanning if they don't press anything after a while.

and pasting the exported markdown file format into pasco we get:

'Meta-data' commands are commands added in-line to the tree file which changes the function of that part of the language. For example, we have commands that stop the tree automatically going back to the top - and commands that help with spelling. For example, If you want to change create a command to go back you would type this in your file

	Dog
	Cat
	Bird
	Go Back <meta data-back-n-branch="1">	   			

This is the Control data command - back-n-branch. This means you can set an action on the press of this command to go back up n levels. Maybe one or two branches if necessary.

The following is an example markdown for a metadata in a node

I have something to say<meta data-audio="some/audio/file.mp3" auditory-cue="<TEXT>">

It's the replacement text for utterance for cue

Stay in Branch commands

To stay in a branch simply add this at the top level item:

<meta data-stay-in-branch>

e.g.

I would like<meta data-stay-in-branch>
	Pizza
	with Cheese
	with Pepperoni 

To go back one level or several you can use use back-n-branch=N where N = number of branches to step back to. e.g.

<meta data-back-n-branch="1" data-back-n-branch-notify>

And lastly, to select an item and then exit use select-utterance

<meta data-select-utterance>

Spell metadata

Spelling is possible. To start it you need a branch that defines a alphabet. So the root node should have spell-branch:

I'll spell it <meta data-spell-branch>

To spell a letter use spell-letter e.g. <meta data-spell-letter=" ">

spell-letter="<A LETTER>"

It's the replacement for the text existed in that node. Instead this value will be added to list of letters

spell-finish

The option to delete the last letter selected

spell-delchar

The option to remove last inserted character in spelling queue

spell-branch

Considers all leaf of that branch to be as spell letters, It used for defining where spell function should be used.

Spelling with prediction

Firstly we need to tell pasco that there will be changes to the layout after each selection:

<meta data-spell-branch  data-spell-update-dyn-onchange>

Next we need to define some aspects of prediction. For Word prediction we define it with data-dyn=spell-word-prediction:

<meta data-dyn="spell-word-prediction" data-words-file="trees/Spell_Prediction/bncfrequency.json" data-max-nodes="3" data-spell-finish data-predict-after-n-chars="3"

data-words-file="trees/Spell_Prediction/bncfrequency.json" 

Next we say the number of predictions that are going to be presented:

data-max-nodes="3" 

And lastly, we can define after how many letters are spelt before we get predictions:

predict-after-n-chars="number"

We can also use next letter prediction. This is done with data-dyn=spell-letter-prediction:

<meta data-dyn="spell-letter-prediction" data-words-file="trees/Spell_Prediction/bncfrequency.json">

Audio metadata

audio="<PATH/TO/AUDIO/FILE>"

Plays the selected audio for cue and main voice

cue-audio="<PATH/TO/AUDIO/FILE>"

Plays the selected audio for cue voice

main-audio="<PATH/TO/AUDIO/FILE>"

Plays the selected audio for main voice

Before you edit the raw language file you must remember some rules!

1. Use a Plain Text editor. Don't use Microsoft Word, Wordpad, Apple Pages or similar. When you have a plain text editor - no fancy formatting like bolding text or underlining is possible. Which is great for pasco - as it will mess with its head!. The only formatting you can use is a tab to indent the text (or use spaces). For example:

   Copy

    Chat
    	Social Chat
    		Alright Mate
    		How's things?
    	Polite Chat
    		Good morning
    		How are you?
    		Anything I can do for you today
    Care Messages
    	Body Parts
    	Medical equipment
    		Chair
    		Bed
    I'll spell it

2. Tabs and Spaces don't mix! Each line can start with either spaces OR tabs. Not both

So you cannot do this:

[space-space]I'll spell it

i.e. here the file has started with a space - but then given a tab. The next line has two spaces. In many text editors this is difficult to see - but effectively we have messed up pasco. Does it look at spaces or tabs?

1. Cues can be put in brackets

for example if you wanted the person to be able to say "Hello World" (Main Voice) but a cue to be "Hello" we could do this:

Hello World(hello)

Editing with Notes on iOS

Unless you have a fancy iPad Pro - or are using an external keyboard you cant use tabs on the iPad - so you will have to use spaces instead. Where you would use one tab to indent - do the same with a space. Keep the number of spaces the same so your file looks nice and neat.

Editing with Notepad on Windows

Getting started with development

To get you up and running this should get you to the point where you can work on the normal web version:

git clone https://github.com/AceCentre/pasco.git
npm install
bower install
npm run dev

For the iOS version you will need to be on a mac with XCode. Here are the commands to get going with this:

npm run cordova-dist
cd cordova
cordova platform add ios
cordova run

You should find the xcode project in cordova\platforms\ios\pasco.xcodeproj

Having problems at this stage?

npm install --upgrade cordova@latest
npm install --upgrade cordova-ios@latest
npm install --upgrade ios-deploy
npm install cordova-icon 

How is the project structured?

i.e. what goes where.

What platforms are supported?

Device requirements

So for the full-feature verison of pasco look at using it on a iOS device (iPhone, iPod Touch, iPad).

Switch interface

Speakers / Headphones for cue / main

If you wish to use a second speaker - we recommend right now to use a wired headphone - and just the device's own internal speaker.

Setup

When you first load pasco you will see a quick setup screen. It should look a little like this

Depending on which device you are using these screens may look slightly different - and depending on whether you have your screen in potrtait or landscape. But all the same options should be available.

What do all these options mean?

• Locale Which language are you wanting the app to be setup in? Changing this will change the language of all the menu items and configuration buttons.

• Choose an example tree "Trees" are what other communication apps call "Pagesets" or "Gridsets" or similar. We call them "Trees" in pasco because it defines how language is navigated - like an ever expanding network of branches. Here we have some example trees to get you started. Choose one to see some examples of pasco.

• Automatic Scanning or Manual. Choose Manual if you want to try it out without a switch - or if you wish to try it with two or more switches. If you want to use it with one switch select Automatic scanning. When you do this, make sure your switch is set to Enter

• Cue Voice is the voice to hear the auditory cue. Typically a user may hear what they can select right now with a cue (sometimes called Private voice). You can choose the voice, the rate, pitch and volume of this voice. You can try an example of the settings by pressing the Green play button

• Main Voice is the voice that others will hear - typically the communication partner. Sometimes people amplify this using a secondary speaker. In other software this has typically been called the Public Voice.

Play/Start screen

Once you have pressed the Green "Start" button at the bottom of the quick setup screen - or you click on the small "Play" icon anywhere else in the app you should see a screen a little like this below.

The screen has two main components. The grey navigation bar at the top where you can access "Configuration", "Help" and "Edit" options, and the main language display area.

Let's now give you a quick overview of the parts of the screen.

The navigation menu

The navigation menu (see left) is a small 4-way directional navigational tool to allow a communication partner to navigate the currently loaded language tree. Pressing up - moves up in the current branch, down - moves down and left will move into the next branch - if available - or select the current item. Right will go back a level - if there is a level to go to.

Although originally designed for the communication partner we have found some clients who have a small thumb movement to be able to use this

To Resize and Move the navigational menu

Simply press and hold and then release. It can take a little while to work out the timing. When you release you are looking for a dotted line to appear around the cursor (see right above). By dragging the corners you can resize the menu - larger or smaller. Want to get it back to the default size? Hit the reset button in the middle when in this resizing mode.

To move the menu press and hold on it as above and simply drag it to somewhere you need it on-screen

The Edit button

Pressing the edit button (the small pencil icon in the grey bar at the top of the screen) gives you access to a language editor.

When in edit mode - select an item in your language and press the small green plus signs to add an item or the red minus sign to remove an item. Simply write your message. If you want a different cue for the item simply type it in brackets. E.g. If you wanted the main message to be hello, how are you? but the cue to be hi you could write in your box hello, how are you?(hi)

You can't view cues or advanced meta-data commands in edit mode We want to make pasco as simple to use as possible. By providing some other means to view the cue would make this messy. So right now you can just listen for the cue - and edit if you don't like what you hear

Note it can be difficult to navigate to somewhere else in your tree on iOS - so do have the Navigation menu available to you when using this mode - it really helps!

As well as adding or removing phrases you can also add or remove recorded messages on iOS. To do this - select an item and you should see a small "spanner" item at the top right of the dotted area around the word/phrase selected. Tap this and you can now press the record button to add your own recorded main or cue voice.

👍 You've successfully installed and setup pasco!

Overview

With meta tags you can specify attributes for any node in the tree file. For example. You can implement back function in a branch, When you select back node then it will move up from Its current position in the hierarchy. In the example below when "Go Back" has selected it will move to "Animals".

Animals
	Dog
	Cat
	Bird
	Go Back <meta data-back-n-branch="1">	   			

Meta tag is a regular html tag, And here is how we add attributes to a node. <meta data-name="value" [...]>. All attributes should start with prefix data-, Following with attribute name. Note that tag can contain more than one attribute.

In example above back-n-branch specifies a behaviour for when It's selected.

auditory-cue

type: string

Auditory cue specifies what should get uttered when user scrolls over nodes, AKA move to next or previous.

auditory-main

type: string

Auditory main specifies what should get uttered when user selects a node.

It's not applicable to spelling branch

back-n-branch

type: integer (greater than zero)

To move up n levels in the tree hierarchy when the node has select.

back-n-branch-notify

Back n branch attribute performs back functionality. And it does not utter (with main voice) the node itself. As selecting a node does that. When you include back-n-branch-notify it notifies the user by uttering with main voice.

audio

The audio to play instead of utterance with speech synthesizer. It applies to cue and main voice.

cue-audio

The audio to play when user scrolls through nodes. cue-audio overrides audio attribute when you specify both.

main-audio

The audio to play when user selects a node. main-audio overrides audio attribute when you specify both.

locale

type: string

Specify locale for a node. At the moment this attribute has only effect on speech synthesizer voice selection. At config you can specify what voice to use for every locale, When you apply locale to a node it will change the voice accordingly.

Here are possible values you can set as locale.

• "en-GB" English (UK)

• "de" German

• "fr-FR" French

• "es-ES" Spanish

• "ar" Arabic

• "gu" Gujarati

• "cy" Welsh

You may also use only language part of locale. For example instead of "en-GB" if you use en. pasco will match it to first locale it finds with same language.

cue-locale

type: string

Same as locale, This attribute is designed to override locale for cue voice. cue-locale precedes locale when both are set in a node.

main-locale

type: string

Same as locale, This attribute is designed to override locale for main voice. main-locale precedes locale when both are set in a node.

spell-branch

pasco enables spelling with this attribute. You have to assign it to top level node that contains spelling branch. Here's an examples.

I have something to say
I'll spell it<meta data-spell-branch>
  A
  B
  Finish<meta data-spell-finish>

You may also set the attribute to root node like this.

<meta data-spell-branch>
A
B
Finish<meta data-spell-finish>

spell-delchar

When user selects a node with this attribute. It removes a letter from existing spelling session.

spell-finish

You have to use "spell-finish" to finish the existig session. It also notifies with main voice similar to selecting a node outside spell-branch.

spell-letter

type: string

You may use spell-letter to specify next letter to add in the spelling session. By default it is going to use the text of the node itself.

spell-word

type: string

You can use spell-word to complete a word in the spelling memory. Let's say you select letter A and then select spell-word="apple". Then it will remove registered letter A and then adds apple.

Spelling process allows the user to add more than one word by adding space in between them.

spell-update-dyn-onchange

When this attribute is given to spell-branch node. It will update all dyn nodes inside this branch.

This attribute is primarily used when spell-branch node contains dynamic nodes. With dyn="spell-word-prediction" and/or dyn="spell-letter-prediction".

stay-in-branch

With stay in branch you can specify a branch to start over from when user selects a leaf node in that branch. Here's an example.

I have something to say
I'll spell it<meta data-spell-branch data-stay-in-branch>
  A
  Finish<meta data-spell-finish>

change-tree

When user selects change-tree pasco tries to load the given tree and open it. Then it starts from beginning in the new tree.

change-tree-by-name

type: string

Change by tree is similar to changetree. Except it loads the tree from saved trees inside pasco. You can manage saved trees at Vocabulary section of config page.

no-main

When you select a node that has no-main it will not utter main voice.

webhook

type: url (string)

pasco has a set of webhook attributes that enables users to perform an http request to sites that support cross-origin xhr requests. It is specifically designed for use of iot webhooks like zapier.com, Here's an example.

Add a record <meta data-webhook="https://hooks.zapier.com/hooks/catch/.../" data-webhook-method="POST" data-webhook-content-type="application/json" data-webhook-body='{"Name":"random row"}' data-webhook-success-message="Did add a record"/>

webhook-method

type: string

Specifies method of the webhook request. Default value is POST. Possible values are: GET/PUT/POST/DELETE, etc.

webhook-content-type

type: string

Specifies request content type of the webhook request. Default value is application/json.

webhook-body

type: string

Specifies request body of the webhook request. Default value is {} (Empty json object) when content-type is application/json. Otherwise body is empty.

webhook-success-message

type: string

You can set the message to utter when pasco receives success response from this webhook request. You can add this attribute to a webhook node.

webhook-skip-validating-response

With this attribute added to webhook. It will skip validating response when response is OK (200). This attribute was specifically designed for zapier.com webhook. By default it is false.

webhook-modify-headers

When this attribute is true, Only then webhook will actually modify request headers. Default is false, It is designed for when cross-origin server does not allow for modifying headers. At the time of design zapier.com webhook does not allow changes on headers.

dyn

type: string

Dynamic attribute introduces dynamic nodes into pasco. Below you can see possible values.

dyn="trees-switcher"

Lists saved trees, Each as a node. And when user selects any. It will change the tree to that.

dyn="spell-word-prediction"

Offers some words as prediction of current spelling. Here are the accepted attributes for this dyn. word-file, max-nodes and predict-after-n-chars.

dyn="spell-letter-prediction"

Predicts order of alphabetic letters according to current spelling status. Here are the accepted attributes for this dyn. word-file, max-nodes, predict-after-n-chars and alphabet.

words-file

This attribute is required when spell dyn has set to a node.

Only for spell dyns

max-nodes

type: integer (greater than or equal zero)

Maximum number of nodes to show as predictions. Default: 3

Only for spell dyns

predict-after-n-chars

type: integer (greater than or equal zero)

Start predicting after n letters has inserted when spelling. Default: null (no limit)

Only for spell dyns

alphabet

type: string

String of letters to use for prediction. Default: abcdefghijklmnopqrstuvwxyz

Only for spell predict letters dyn

Path Value

Path is of type string that is expected to be http(s) url or relative path in the package or relative path from base url.

Boolean Value

No value is required, Since it is a boolean attribute, example <meta data-attr-name>. You can also set Its value to false or true.