iq-eq-us/dot-io

Dot I/O is a free, open source, web based training tool designed to forever change the way we learn to type.

Introduction

Dot I/O is a free, open source, web based training tool designed to forever change the way we learn to type.

Instead of measuring digital literacy with a single, all encompassing metric (words per minute), Dot I/O will measure your progress via six multivariate metrics: (tWPM, sWPM, ChM, CPM, StM, CM). These complementary metrics are designed to allow you to calibrate and track progress in a way that is meaningful to your specific goals, and to help you build a custom HCI profile that's just as unique as you are. With Dot I/O, you're more than just a number :crashWave: dot i/o is a testing/training tool for Keyboard users. It allows these users to practicing their typing, trigrams, and chording.

Dot I/O features some cutting-edge capabilities especially designed for the next generation of intelligent peripherals. Dot I/O is the first ever training tool with the ability to utilize the CCOS Serial API to establish a direct connection to your device while you practice. This means custom tailored practice sessions can be automatically generated from your embedded memory & history, that your custom constituent chord inputs can be highlighted on a virtual device in real-time, and that you can access advanced configuration options for your device directly inside of the web interface. That's just what is already available, and only scratches the surface of what will be possible.

How to Support

NOTICE: You need to sign your commits or your PR will be blocked. See this article for the steps.

In general, we follow the "fork-and-pull" Git workflow.

1. Fork the repo on GitHub
2. Clone the project to your own machine
3. Commit changes to your own branch
4. Push your work back up to your fork
5. Submit a Pull request so that we can review your changes. In this request please put in a summary of the changes. (all pull requests will be reviewed every Friday)

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

To join our active discord please click here: https://discord.gg/rWBuHeR9yU. To get the Developer Role within the discord please ping '@iq-eq Rep'

Dependency Installation

After you have successfully downloaded the source code for the Dot I/O project, navigate to the root directory in your preferred terminal application. I prefer to use the integrated terminal inside of VSCode, the recommended IDE for working with this project. Once there, run the npm install command to install all of the required dependencies for Dot I/O to run. The output should look something similar to this:

$ npm install

> postinstall
> cd ci-cd && npm install


up to date, audited 14 packages in 1s

6 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

up to date, audited 1222 packages in 4s

123 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

As long as there are no error messages present, you can assume the previous step was successful.

Running Locally

To run the project locally on your development machine, navigate back to the root directory of the project, and run the npm start command. This will execute the start script located in the [package.json]file in your root directory. This will in turn execute snowpack dev, snowpack being the frontend build tool that bundles and serves your project.

If successful, you should see something similar to the following output:

$ npm start

> start
> snowpack dev

[11:42:12] [snowpack] Ready!
[11:42:12] [snowpack] Server started in 60ms.
[11:42:12] [snowpack] Local: http://localhost:8080
[11:42:12] [snowpack] Network: http://192.168.1.155:8080
[11:42:12] [@snowpack/plugin-typescript] 10:41:12 AM - Starting compilation in watch mode...

⠸ watching for file changes...

Snowpack will automatically open the local development version of the site in your preferred browser. However, if Dot I/O is not opened automatically, the site can also be found at the url posted in your terminal by snowpack, most likely http://localhost:8080.

Anytime you update a file in your IDE or text editor, snowpack will pick up on your change and update the site automatically, through a feature called "Hot Reload." However, Hot Reload can be finicky at times, so it can be worth doing a manual refresh of the browser if the site is not behaving like you expect.

Next Steps

For more information, see the articles on architecture, testing, and deployment

dot-io's Issues

Defect: non-test specific settings are reset anytime you use any Dot I/O feature such as new test, change module, etc.

Defect: a "failed" CPM test still shows up on CPM dashboard

Steps to recreate

1. Clear storage
2. Take a CPM test. While testing, use chords / make errors so accuracy / chorded requirement is not met
3. Finish test. Go to dashboard.
4. Observe that the dashboard shows the CPM value

See video:

BugCPM.mp4

Defect: Issue with "Practice slow chords" when you have chords over 150 wpm

Steps to recreate:

1. Complete all chords in "English 200" at least 10 times each.
2. Have at least one with an aWPM greater than 150 wpm
3. Have "Practice slow chords" setting on
4. Observe that the words generated are predominately just the word that you typed over 150 wpm.

Faster steps to recreate:

1. Edit local storage key "CHM_LEXICAL" with this json: practice-slow-bug.txt
2. Refresh the page, go to English 200 and open statistics, notice how only "and" is above 150 wpm
3. Click focus into test and see it is only recommending to practice and for the most part:
   
4. Turn off "practice slow chords" and finish the first line. Note, because of #42 you can't regen the test or anything, you must stay on the same test.
5. Notice how now the new lines recommended are properly recommending chords to practice

When fixed, notify in this discord thread:
https://discord.com/channels/861730583092658206/1112929906100293683

Enhancements: beginner best practices

a few things we picked up on from the AAERT show

1.show finger placement on the virtual device
2.space bar at the end of the CPM test is not wanted
3.backspace at the letter tier should not be required

Accessibility: Optimize site for mobile

Enhancement: improve legibility of the tick marks on HUD progress bar

Right now they are incredibly hard to read

Defect: "practice slow chords" showing chords faster than the speed goal on ChM-All Chords

So the effect is that you never progress past the first 6 it recommends you. For example, see this screenshot where I have done over 100 of the same 6 terms and it still showing chords that are faster than the speed goal.

If you turn off "practice slow chords" it starts to recommend new ones.
Same for if you use 95%

Defect: mobile hamburger menu not accessible / doesn't work

The hamburger here doesn't do anything when you click it.
I was trying to get to the Connect button

Need to omit/blacklist non-string chord outputs

Enhancement: filter serial devices by vendor ID

This would make it so only CharaChorder devices show up in the browser connect by serial window

Development/contribution process

Can someone write into the Readme the steps to take to actually contribute to the project. It isn't clear to me what the steps would be. What are the branches/environments, etc.

Make PRs against what branch, etc?

Snowpack is not recommended anymore

According to the snowpack homepage it is "no longer actively maintained and is not recommended for new projects". They recommend using "Vite for a well-maintained Snowpack alternative".

I don't have anything against snowpack in particular in fact I think its mission was amazing it's just that vite and snowpack do the exact same thing effectively and they came out around the same time and vite just won so snowpack faded away.

I think we should replace snowpack with vite what do you guys think? If you guys agree I can make a pr for this pretty quickly.

Enhancement: combine the "connect" and "disconnect" buttons into one

You can only be one state or the other, so there is no need for both

Enhancement: ask if user wants to back up layout before entering bootloader

Speaking as someone who just lost their keymap while doing a firmware upgrade and already cleared their downloads folder where presumably it was... this would be a great Quality of Life upgrade

Need an ability to manually blacklist chords from your library which you do not wish to practice (ChM module)

For duplicate chord outputs. I would suggest automatically removing duplicates however this would require the user to select which input they want to be displayed for every duplicate chord. Ability to have the option to also delete chords from your library as part of this process would be great as well

Link GUI key mapper - www.charachorder-config.com

Link to popular mapping tool by gekko

Enhancement: default settings on chording tiers should introduce new terms once the user has mastered the existing ones

Perhaps a "beginner mode" and an "advanced mode" since it seems some users prefer the way it is, too.

Discord discussion with users: https://discord.com/channels/861730583092658206/1114293173662007418

Defect: all chords tier accuracies greater than 100%

The AWPM measured looks wrong, too

Enhancement: remove spaces in letter tier to reflect the fact that space bar is not needed

Improvement: Improve device selector drop down

Improve the UI of the dropdown used to select emulated devices.

Enhancement: instructions say to "Continue" but the button is "Move to Next Module"

Also, I believe it should say "Move to next tier" not module, as I understand it the CPM is the module and then Letters/trigrams are tiers. We should be consistent in the language. Also "completed current tier"

Unless I have that backwards @rileykeen (I hope not!)

Enhancement: remember last connected CharaChorder device and automatically connect

Make sure there is a way to disconnect and change to another CharaChorder device

Multi-language support

User has a chord for perché d'età () (Italian) however dot i/o is asking them to type perch{ d-et' *( in the prompt. We may need a language selector such as this to accommodate unless we can find a way to automatically detect the language:

Improvement: Add a notification button

Description

To better relay what bug fixes, upgrades, and features have been added to the site we would need to add a notifications button that will allow users to know what has been fixed and when it was fixed. This will help us better communicate with users what was changed.

Requirements

• The announcement icon should go on the far right of the icon bar.
• Upon pressing this button a side column should be exposed and show the latest updates (if any) in card format.
• Users should be able to close this column by pressing the icon again or pressing anywhere outside of the column.
• If there are no updates, or if the user has already viewed the latest updates show, 'Nothing new to show!'.

Fully fleshed-out designs will be added to this description soon!

Announcement Icon example

Enhancement: rename "Save Changes" to "Save to device"

Doing this will make it clearer to the user that it is committing it to their device without having to use the word "commit" which non tech users probably don't recognize in this context

Defect: serial examples on device manager swapped

https://discord.com/channels/861730583092658206/1123080861097672744

does not save progress in ChM tier when switching modules

need to more broadly define when a session ends so that progress will never be lost

Enhancement: once autoconnect is done, read latest layout and chord changes in background

Make sure there is a way to toggle this on or off

Improvement: Add English 500 data set

Add the top 500 English words to the chordsLibrary Library.

Defect/bug: CSS issue on the settings page

Enhancement: allow curly quotes (mostly from MacOS and iOS users)

See this video for reference:

IMG_9805.mov

You can see that what has happened is the user is using iOS and they have a curly/special ' instead of straight. I advised user to turn it off like this:

but maybe we should just allow ' and ‘ to be used interchangeably

Defect: the graph shown by the double arrow button for letters seems flawed in calculations

It seems to be potentially double what I would expect? Maybe counting the space in the calculation

Also, are those two arrows intended to bring you to this screen? I didn't realize this as a user:

It might be worth adding some alt text or changing the icon if it is intended to be a feature?

Enhancement: change the lock icon on "Under construction" modules to make it more clears why users don't progress past a module

Several modules are still under construction and we should make it clear to users

Defect: rWPM/lWPM doesn't consider if you actually typed the word correctly

Not sure it is a huge deal, but can mislead yourself I guess

Enhancement: show actual keymap layout on virtual device

I have remapped the position of the letters on my CC1, it would be good to have the diagram reflect this.

Snowpack not installed as part of npm install, expected?

I was just following the steps to contribute and when I got to actually running got this:

Not sure if expected or others have the same issue or not. I plan to just install snowpack anyway.

It could be a windows thing with snowpack not being recognized in my PATH, will see

New Development: Progress Bar

Adding a progress bar would provide an easy-to-follow visual for anyone on the site going through each module.

Description:
Users want to track their progress while training on dot i/o this progress bar should work depending on what metric we're tracking for the respective tiers. This will give users a visual to follow when working the tiers and modules.

Requirements

CPM Tier:
For each module (letters, trigrams, words, test) each increase will be based on the completion of the word. If the word has been typed equal to or more than 10 times AND the speed of the word's completion is greater than the speedGoal for that module we can increase the completion percentage. The goal number for completion for the entire data set should be equal to the number of words, letters, or trigrams that are being tested.

CHM Tier:
For each module (English 200, All Chords and Custom) each time a word is mastered) typed a minimum of 10 times and the word was completed at an average of 100 wpm for the respective word. Once that is achieved the word can be considered 'Mastered' and we can increase the completion bar. The goal for the completion of the module should be based on the number of words per module.

If there are any questions please @ COChara .

Different CC1 chords between Dot I/O and default chord library

I took the chord list from both Dot I/O program and default chord library of CC1 and found differences (listed in the json below).
I can submit PR for the mismatch and wrong parts (such as began, its) but should I remove ones that doesn't exist in default chord library (such as as)?

[
  {
    "word": "will",
    "dotIOChord": "i + l + w",
    "libraryChords": [
      "i + l + w + DUP"
    ]
  },
  {
    "word": "your",
    "dotIOChord": "r + y",
    "libraryChords": [
      "o + r + u + y"
    ]
  },
  {
    "word": "also",
    "dotIOChord": "a + l + o",
    "libraryChords": [
      "a + l + o + s"
    ]
  },
  {
    "word": "as",
    "dotIOChord": "a + s",
    "libraryChords": null
  },
  {
    "word": "began",
    "dotIOChord": "b + g + present tense",
    "libraryChords": [
      "a + b + e + g + n"
    ]
  },
  {
    "word": "every",
    "dotIOChord": "e + v + y",
    "libraryChords": [
      "e + v + y + DUP",
      "e + r + v + y + DUP"
    ]
  },
  {
    "word": "had",
    "dotIOChord": "a + h",
    "libraryChords": [
      "a + d + h"
    ]
  },
  {
    "word": "its",
    "dotIOChord": "i + t + past tense + plural",
    "libraryChords": null
  },
  {
    "word": "last",
    "dotIOChord": "a + l + t",
    "libraryChords": [
      "a + l + s",
      "a + l + s + t",
      "a + l + u"
    ]
  },
  {
    "word": "near",
    "dotIOChord": "n + r",
    "libraryChords": [
      "a + e + n + r"
    ]
  },
  {
    "word": "quick",
    "dotIOChord": "i + k + q + u",
    "libraryChords": [
      "k + q",
      "c + i + k + q",
      "k + q + u",
      "c + i + k + q + u"
    ]
  },
  {
    "word": "quite",
    "dotIOChord": "e + q + t + u",
    "libraryChords": [
      "e + i + q + t",
      "e + i + q + t + u"
    ]
  },
  {
    "word": "saw",
    "dotIOChord": "s + w",
    "libraryChords": [
      "a + s",
      "a + s + w"
    ]
  },
  {
    "word": "three",
    "dotIOChord": "e + h + r + t",
    "libraryChords": [
      "  + 3",
      "e + h + r + t + DUP"
    ]
  },
  {
    "word": "watch",
    "dotIOChord": "h + t + w",
    "libraryChords": [
      "a + t + w",
      "a + h + t + w"
    ]
  }
]

Defect: it seems possible to unlock ChM tier without scoring 200 CPM in Test tier

Provide link to download latest firmware in device manager if running on older version

Defect: rWPM and lWPM drawn in wrong spot when wpm outside of range of non-dynamic progress bar

You can see here the r and lWPM are beyond the "60" in the scale but they are showing up in the middle

Enhancement: Rename English 200 to "English 300"

It seems like there are actually close to 300 words in the "English 200" tier on ChM. I think we should either rename it or just make it actually the top 200

Reference: End State of dot i/o

Question: why does the test timer (and calculations) start after you finish the first word and not as soon as you start typing?

I would expect it to start once you start typing in the box

Defect: DOT IO shows out of memory error

It happens when I click "populate table" and scroll down several times. Attached are screenshots of the the error message and the output at the end of the console.

Customization: Themes Configuration

Add the ability to customize the colors shown on the site.

Defect: wrong highlighting on All Chords tier

Sometimes it doesn't highlight at all. In this case, the custom chord has the wrong highlighting (it is missing a Dup key highlight)

Defect: average CPM graph shows "NaN" after doing more than one test

Steps to recreate:

1. Clear local storage and start fresh
2. Finish a CPM test
3. Go to dashboard, observe that it does in fact show a CPM
4. Go do another CPM test
5. Go back to dashboard (https://www.iq-eq.io/#/dashboard) and observe that the graph now shows NaN

NaN.bug.on.dashboard-10mb.mp4

Enhancement: add a way to keep saved chord library in sync

As a user, if I want to refresh the chord library that is in use I need to manually edit my local storage. I would like a way to do it from within the application.

Question that probably need answering:
What to do with stats for chords removed from library? Any other considerations?

Also, from a debugging standpoint having a way to delete could be useful

Enhancement: tell user if their browser doesn't support serial API

As a user, it would be helpful if I was told that my browser doesn't support the serial api instead of just showing the generic status: failed to open serial port; may already be open elsewhere.