CommonSense quick-start / noob's guide

[kmnov2017]

What are you talking about ! I have asked a question and hence the post...

[DMA]

What are you talking about ! I have asked a question and hence the post...

You copypasted the same question in 2 threads. Please just don't.

[PancakeMSTR]

I'm starting to try and convert my beamspring using common sense because I've given up on the xwhatsit (can't do the SMD soldering).

I have a question, because I'm getting conflicting results from the (available) documentation and the project page, which is do I still have to modify the controller (remove r5) if I need 24 columns? The default project is now named "8x24," which suggests to me that the project is now setup to work with 24 columns? But I also don't see anywhere where it says I don't need to modify the board anymore.

Here is a picture of my PCB. Let me know if I've read the number of columns incorrectly, i.e. if there are more or fewer than 24.

Actually, looking at the PCB, it seems like it only has 23 columns.

Spoiler:

[kmnov2017]

There are 23 columns on a beamspring. I counted 23 on your PCB as well. So you don't need to remove any resistor on the cypress board.

[PancakeMSTR]

Just finished wiring everything up and tried to test. I'm getting absolutely nothing in flight controller, but I can't tell what I've done wrong. The only thing I can point to is some error in Flight controller saying something like "Scan module has gone insane and had to be shot." Does anyone have any ideas? I'm pretty sure I've wired everything up correctly. The only thing I'm not particularly confident about is how I've wired up ground.

Also in Flight Controller the "UNSAFE" text is lit up red. I read in the docs that this means the thresholds are set incorrectly but I have no idea how to set them?


Here's what Im getting from flight controller:

Spoiler:

Direct Link to image cause insert image not working for some reason: https://i.imgur.com/je53Bxi.jpg

[kmnov2017]

Click "Scan" in Flight controller. It's grayed out, you can see it next to "Unsafe". "Scan" must be in green before you can set thresholds. Click on it multiple times until it turns green.

Once green, click on "Threshold" and then follow DMA's guide on "Configuring Keyboard"

[PancakeMSTR]

Click "Scan" in Flight controller. It's grayed out, you can see it next to "Unsafe". "Scan" must be in green before you can set thresholds. Click on it multiple times until it turns green.

Once green, click on "Threshold" and then follow DMA's guide on "Configuring Keyboard"

K I've gone through the "Configuring Keyboard" guide multiple times now and I'm not getting anything to work. I changed in the config.h file the keyboard type to"BEAMSPRING," which I had neglected to do earlier, and then I got the scan button to turn green, and then the keymonitor to actually display values, but I don't understand how it's supposed to work and I can't get the keyboard to actually type letters. Any tips?

Did you download the source from the Github repo or are you using "Common Sense V1.0?"

[kmnov2017]

In keymonitor, the values are obtained automatically. You do not need to press anything. Just click reset, choose "Max", let the values stabilize for a few seconds and then click "Set Thresholds".

Go to Thresholds, for beamsprings, reduce the values by say 25%. So 4 becomes 3 and so on. Click Apply. Close Key Monitor, go to Config and then upload. This is important without which your keyboard wont work.

To test the keyboard, make sure "Output" is also green. You can find "Output" next to ''Scan''. (Both Scan and Output need to be green). Now type something on the keyboard, you should see key presses represented as row number/column numbers. This basically means your thresholds were correctly set. All keys should produce a unique value.If say 2 (or more keys) produce the same output, then your threshold values need to be adjusted.

As a next step, go to Layout (once again make sure scan and output are green), type a key, you'll see a yellow highlight on the matrix. Set a value on the drop down - this basically assigns a value to the key press. Complete this for all the keys. Click Apply.

Then do a commit. You should see some text that states a certain set of bytes were written into EEPROM. Close FC. Your keyboard should work now.

[PancakeMSTR]

In keymonitor, the values are obtained automatically. You do not need to press anything. Just click reset, choose "Max", let the values stabilize for a few seconds and then click "Set Thresholds".

Go to Thresholds, for beamsprings, reduce the values by say 25%. So 4 becomes 3 and so on. Click Apply. Close Key Monitor, go to Config and then upload. This is important without which your keyboard wont work.

To test the keyboard, make sure "Output" is also green. You can find "Output" next to ''Scan''. (Both Scan and Output need to be green). Now type something on the keyboard, you should see key presses represented as row number/column numbers. This basically means your thresholds were correctly set. All keys should produce a unique value.If say 2 (or more keys) produce the same output, then your threshold values need to be adjusted.

As a next step, go to Layout (once again make sure scan and output are green), type a key, you'll see a yellow highlight on the matrix. Set a value on the drop down - this basically assigns a value to the key press. Complete this for all the keys. Click Apply.

Then do a commit. You should see some text that states a certain set of bytes were written into EEPROM. Close FC. Your keyboard should work now.

I'll give it a try. Thank you!

[PancakeMSTR]

Okay I just simply don't understand why this is not working for me. I've gone through the steps multiple times and can't get any decent behavior. If I mash the keyboard with my hands I get a bunch of output in flight controller but pressing single keys simply doesn't do anything, ever.

Steps:

- Loaded 5251.cfg

- Here is what I'm getting in Matrix monitor: https://imgur.com/gvhUx7p

- I press "Set Thresholds" and then adjusted each to be 75% of what was in the box.

- Press Apply, Upload.

- Press Scan and Output until they are both green

And then at that point it's just anything goes. Like I said if I mash keys I get output but pressing individual keys just does not work....

And, of course, I absolutely cannot get any text output from the keyboard whatsoever.

By the way, if it helps to know, Here's how I wired the rows and columns: https://imgur.com/a/gS8I3jn

Assuming I didn't make an error (and it's definitely possible I did), but that's at least what I tried to do. Also looking at it now I should have reversed the direction I wired the columns in but I don't know if it matters really.

[kmnov2017]

What about GND? The two GND traces on the beamspring PCB must be connected to GND on cypress AND also to the keyboard metal chassis.

[kmnov2017]

Also your matrix seems wrong, you should see 24x8 or 24 x4. I see only 16x8, which means you didn't change the config.h correctly. Once your set the correct matrix in config.h, you must recompile the firmware and flash the firmware once again.

[tentator]

Hi Snacks!
Great writeup: may I give you a couple of suggestions to improve it even further?

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Part 1: Kit and Base Wiring

....

Part 2: Sodering rows and columns

Planning

Now that the base wiring is done, it's time to connect the controller to the rows and columns of the keyboard. The way that CommonSense works is by strobing the columns. When a key is pressed, it's detected by the rows, which are set up to sense this strobing.

The current version of CommonSense has a limitation of 8 rows and 24 columns. If I'm not mistaken, the code can be tweaked to support more rows, but that's a bit beyond what I know how to do so I'll not be going into that.

You do have flexibility to shuffle around the pin assignments, but there are some rules about which pins can be assigned for which purpose and some pins you might be planning to use may already be assigned and that might cause your firmware to fail the build step. I found it easiest to use the default pin assignments if possible. Those assignments are:

Rows: 2[0], 2[3]-2[7], 12[7], 12[6]
Cols: 1[0]-1[7], 3[0], 3[1], 3[3]-3[7], 15[0]-15[5], 0[0], 0[1], 0[5]

DMA notes in the readme that if you need to use more than 17 columns, you must desolder a few components from the dev board. These components are C41, C42, and R5. DMA elaborated on this that it's possible to do without desoldering by simply substituting for pins which do not have external components attached to them. Again, this is only if you need more than 17 columns.

I'd add some example/pictures of the standard pinout at least, what do you think?
If you need I have some pictures I can provide.. beamspring setup 3278.. 4x20..

Keyboard

So now we know which pins on the board we're interested in, but what do these need to connect to on the keyboard? Well first, you'll need to take the keyboard apart in order to get to the PCB. CommonSense should work on most if not all capacitive keyboards, but most frequently people seem to be using it on Beamspring or Model F so I will use those as an example.

Once you've got your keyboard apart, you need to trace the rows and columns of the matrix to some point on the PCB where they terminate. So for example on an IBM 5121, the place where these lines connect is the big edge connector. Usually it's easy enough to trace the lines just by visually inspecting the PCB. You don't need to map out every key in the matrix, you just need to figure out which lines are rows and which lines are columns.

....


-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Part 3: Configuring, building, and flashing firmware



Building the bootloader

In the project explorer on the left side of the screen, find the Bootloader project.

• Right click the project name and select "Set as active project".
• Right click again and choose "Device Selector". In the popup pick "CY8C5888LTI-LP097"
• Press Shift + F6 to build the bootloader

I'd suggest to put here also the step where you flash the bootloader and see everything is fine (so ctrl+5 while it's plugged in USB), theoretically the firmware can then be flashed also directly with flightcontoller in case..

Building the firmware (dry run)

This will be similar to what you did for the bootloader. This is just a dry run, but don't skip it! Make sure to do this before making any changes!
In the project explorer, find the Firmware project.

• Right click the project name and select "Set as active project".
• Right click again and choose "Device Selector". In the popup pick "CY8C5888LTI-LP097"
• Press Shift + F6 to build the firmware

...

Pins Assignments

Note: This part is only relevant if you deviated from the default pins. You can skip this section if you went with the default assignments. Though, I would recommend stepping through it just to confirm everything looks good.

We need to tell the firmware which pins to use. Still with your active project set to Firmware, locate and double click the node in the tree called "Pins" (it will be under "Design Wide Resources"). A view will open showing all of the pins on the chip. We'll be making our changed in the pane on the right ride.

• Go through each of the "cols" and choose the corresponding pins from the drop down lists
• Do the same for each of the "rows"

There are other changes we can make here but I'm not going to be going into those.

Here I would suggest to copy the pins from the 8x24 projects in case one is following the default new/better arranged pin order as done by DMA in the new default firmware and in the picture he put in the readme:
https://github.com/dmaone/CommonSense/r ... pinout.png

Also notice that in this setup it has a warning about "array subscript is above array bounds [-Warray-bounds]" that I guess DMA can confirm is harmless. It's in globals.h:

Code: Select all

#define CLEAR_BIT(VAR, BN) VAR &= ~(1 << (BN))

Building and Flashing the firmware

With the configs out of the way, it is time to build and flash the firmware for real.

• Plug the USB-A side of the board into your PC.
• Press Ctrl + F5

A popup should appear. This is where you select the board to flash. Click the top-level item that appears in the picker window. Then click the "Port Acquire" button. A sub item should appear. This is your target, select it and click the "OK / Connect" button.

The first time you do this, it will most likely say you need to update the kitprog. To do that, open the application called "PSoC Programmer". Go to the "Utilities" tab and click the "Update Firmware" button. When it finished, pop back over to PSoC Creator, and proceed with the build/flash as previously described.

Hopefully it builds and loads onto the board with no issue. If you have a build issue at this point, you may want to start with a fresh pull from the github repo to get those sweet sweet defaults back. Then try changing one setting at a time, rebuilding, etc. until you zero in on the issue.

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Part 4 - FlightController

Preface

FlightController is the piece of software DMA wrote to configure the controller. It is built using Qt. Qt is a framework for building cross-platform applications. This means that FlightController can be built on / run on Windows, OSX, and Linux.

So there are two paths that you can take for the next part:

1. You can download the compiled binaries from the Releases section of the CommonSense github repo
2. You can compile the app your self

For now, I'm just going to link to the compiled app.

https://github.com/dmaone/CommonSense/releases

Download the exe and you're good to go.

Getting Started

Plug the controller into your pc this time with a usb cable via the micro usb connector on the dev board. Make sure not to ever plug both ends of the controller in at once. I don't know the risk is but you've made it this far, don't fry your board!

Then launch FlightController. The application will immediately begin looking for your device and automatically connecting to it. If it fails to find / connect to your controller, hit the reconnect button. If it still doesn't connect, you may need to go back to section #3.

After connecting, all of the buttons on the left side will become available. Click the status button, the text area on the right should output something about CommonSense. Hey! That's a good sign!



So we know with 100% confidence that the firmware is flashed to the board. But before it will work, you need to initialize it with a config. DMA has kindly packaged some configs for you to start with. Go to Config > Load from file. Then browse to the CommonSense folder you extracted earlier. Next into the folder named "misc". Inside there's a config file for two keyboards. Pick the one that matches your keyboard. Don't worry if your keyboard is something way different; this is just a starting point.

this part is a bit confusing in my opinion: I would state it clearly that when you connect the first time a first-flashed new controller the first time it will surely go mad and the red status called "UNSAFE" will turn on: maybe it's enough you put in bold and red that sentence above "But before it will work, you NEED to initialize it"..

Pick one of the files and load it. Now FlightController has a bunch of settings set. Next you will upload it to the controller by going to Config > Upload. This uploads the config, but does not "commit" it to the eprom (which is a separate step). The config you just uploaded will only last as long as your FlightController "session". But that's perfect because for now we're still configuring.

Thresholds

This is the part of the application where you define what the controller considers a keypress. And you do it PER KEY. Okay, it's actually not that bad. Hopefully your keyboard is not wildly different from key to key. Keep the thresholds window open while we do the next part.

I'd leave something similar to what DMA explained in the readme also here:

Click "Key Monitor" button.
Click "Start!". Get the idea of levels that should be there - press keys, observe readings going up and down. Small numbers below 7-segment indicators are min/avg/max.
Click "Stop!". Select "Max" into dropdown near the "reset" button, click "Reset", "Start!". ("Min" in case of beamspring)
Wait 15 seconds or longer, while readings stabilize. (Type once every key in case of beamspring)
click "Stop!". Click "Set thresholds". Close window.
Click "Thresholds" in the main window. put a small positive value (I use 5) into adjuster spinbox, click "Adjust".
Click "Apply".
Close threshold editor. Select "Config -> Upload" in menu. Test. Once you're satisfied with results, "Command -> Commit".
If you get thresholds wrong - there will be a red "UNSAFE" light in the status bar and keyboard will refuse to produce output. It's supposed to retest settings after you upload. If it doesn't - click "Scan", it will try to restart scanning.

...

Layout, Layers, Macros

These sections behave just like you'd think and are pretty easy to navigate.

believe it or not but I cannot find much about how to configure Macros and Delays..
I think there are a couple of bugs: one minor is that if you do a macro that presses something while you are in another layer it does not go back to the previous layer anymore or otherwise there is no way to fix the layer afterwards.. one major is that the tap macro does not seem to work at all.. no matter what delay I set..

Delays & Hardware
I don't yet have a good grasp on these sections. As I learn more I will fill in this post. What I'll say for now is that if you have odd behavior coming from your keyboard, I'd suspect something in one of these two sections needs to be tweaked.

Oh and you can select what the expansion header on the board does (the little part that can snap off). You can choose from (1) nothing (2) solenoid (3) led lock lights

I'm happy to see the new version 1.0 from DMA, it's a great improvement when comparing to the previous version I was using some months ago.
Also happy to see that the community works!
Other than this, maybe I'd now finally figure out how to implement "tap dance"! (yes, my friend DMA, the tap macro does still not work.. )

Kr,
tent:wq

[tentator]

I think there is a typo in this section of the documentation:

ExpHdr (AKA "Solenoid connector")

Configured to blink the kit's LED on keypress. 12.4 is a CapsLock LED, 12.3 - NumLock.

Leave it alone, unless you really know what you're doing. You can permanently damage GPIOs if you fuck up here.

DO NOT POWER ANYTHING FROM GPIOs. Max GPIO source current is 4mA. FOUR. MILLIAMPERES.

So, ExpHdr0(12.3 by default) would be "enable" line, and ExpHdr2 (2.1) is the "fire" line. Delay settings are in "Hardware" section of FlightController. ExpTgl "USB scancode" toggles between normal operations and "all GPIOs are pulled to the ground".

ExpHdr0 should be 12.2 by default now (and otherwise it would be conflicting sentence with the second line where it's stated that 12.3 is NumLock)

So in the end I'd document it also in the picture with the pinout that the solenoid driver should be connected to 12_2 (enable) and 2_1 (fire) so that in xwhatsit's solenoid controller it will go to pins 2 and 4 respectively.

I also have a frankenstein picture of my interpretation: let me know if I understood it all right

Solenoid.png (542.56 KiB) Viewed 6075 times

Kr,
tent:wq

[tentator]

is there anybody able to confirm the above with the now new default 24x8 config?

[tentator]

I just tested it, and can confirm solenoid now works on 12.2! please snacks, can you update?

tent:wq

[snacksthecat]

Sorry guys, I fell of the radar for a while. Thank you very much for the feedback. Particularly @tentator. Super thorough and on-point.

I'll fold in these changes as well as some other general tweaks to bring it up to speed with the current commonsense release this weekend.

My apologies for any mistakes that may have caused anyone frustration.

[snacksthecat]

Sorry I didn't get around to updating yet. I may take a little bit because I'd like to run through it on an actual board. I have one I'm planning to convert but just need the time.

[Baby]

Thank you!