Category Archives: How-to’s

The quest for a full featured Linux experience on a tablet

I recently fulfilled a dream of mine that I let stay a dream for too long – I bought a tablet PC which can run a full desktop operating system on a normal CPU architecture.

From as far back as my first time shopping for a laptop as a grammar school student, I can remember being impressed by the (at the time, thick and clunky) “tablet” laptops which could accept pen\stylus input. The type of computer that would run Windows XP Tablet PC Edition. These were far more expensive than conventional laptops at the time, and way out of my price range.

I spent the years, perhaps over a decade that followed chasing this idea of mobile computing. From my Palm i705, to my HP iPAQ H1910, to the Cassiopeia running Windows CE 1.0 that I found at a garage sale, to the many iPads I have bought throughout the past decade… but I’d never owned anything that quite scratched that itch for a truly mobile full desktop experience.

I steered clear of Microsoft Surface for a long time, in no small part because of the (in my opinion) disastrous initial launch where many of them contained ARM processors and only pretended to be full featured computers… tricking non-savvy consumers by running something which resembled Windows, but couldn’t run most Windows programs due to the CPU architecture.

Recently, after AT&T took away the grandfathered iPad unlimited data plan I had for nearly a decade, I felt a new freedom to explore what was out there in the tablet market. By now, it seems that a bit more is available out there with full desktop capabilities in a tablet form factor, but it still for some reason seems to be a very niche type of product.

I found the Chuwi UBook X, which had a very similar look and feel as a Microsoft Surface tablet, but seemed to be significantly cheaper for better hardware specs. I was intrigued, especially as I discovered that there is a large community of people out there running Linux on their Microsoft Surface tablets. I decided to give the UBook a try and picked one up.

Linux on the UBook

The Windows experience out of the box on the UBook was very impressive. I found the screen auto rotation and on screen keyboard to be close to as intuitive as what I was accustomed to from my years of iPad usage. The voice dictation and keyboard autocorrect\predictive text was also fairly solid. Windows 11 on the tablet is definitely a pleasant user experience. Pleasant enough that I am keeping it intact, and my attempts to get Linux working so far have been as a dual boot.

I tested several different distributions and desktop environments, curious to see how some of the ones I was accustomed to running on my desktops were working with mobile support. Unsurprisingly, traditional desktops found in Linux Mint distributions like MATE and Cinnamon were basically unusable on mobile out of the box. I’m sure you could make it work with heavy modification, but lacking even the basics like an on screen keyboard, these desktop UI’s were clearly not going to be my picks on this device.

I tested Ubuntu 22.04, which by default comes with a GNOME desktop interface. I found this to be competent and usable on the tablet, so finally we were getting somewhere! But, despite the interface claiming to have auto screen rotation capabilities, I found that my tablet would never exit landscape mode.

In search for a solution, I found that a lot of folks are running Fedora 39 on this type of hardware. Fedora 39 comes with GNOME out of the box too, but with a bit of a better default configuration for my preferences, such as eliminating the Ubuntu sidebar. Fedora is also a much more bleeding edge distribution, offering newer kernels and drivers, which is often helpful when you are running newer or more niche hardware like this.

I installed Fedora 39 and immediately it felt like it belonged on this device, except for one problem… the screen still didn’t rotate!

Troubleshooting Linux automatic screen rotation and accelerometers

So, I am now faced with the reality that a newer kernel and drivers won’t save me. My accelerometer doesn’t seem to work, whether I’m running a 5.x or 6.x kernel, whether I’m on Ubuntu or Fedora… but why? I found reports from other people online saying their accelerometer was working on their UBook, but with some other issues, like the screen rotation being 90 degrees off.

I began to research, consuming content like this video about how to fix flipped screen rotation on Linux, in an effort to learn more about how these accelerometers worked and why mine didn’t work… It seemed like this must be a lower level issue than just GNOME not working, so I wanted to find out how the drivers from these sensors work and how to troubleshoot them.

I first learned of the monitor-sensor command, which seemed to be a lower level way to debug what was happening. Upon running this command, my screen orientation was always reporting “left-up”, regardless of the actual position of the tablet.

Still not sure about where the disconnect was here, I dove deeper. The monitor-sensor output talks about “iio-sensor-proxy“, so what does that do? I learned that the actual hardware for the accelerator in Linux is handled by a subsystem called Industiral I/O (IIO).

I further learned that their device handles are named like “iio:device#” in /dev/. I soon found my accelerometer sensor located in “/dev/iio:device0” and learned that its raw readings are available in the path “/sys/bus/iio/devices/iio:device0/”.

This finding led to an interesting discovery, the raw values were not always exactly the same each Linux distribution I tested, but they seemed to be unchanging while being observed. They were not updating when the tablet was rotated physically.

I dove deeper into the driver support, and found that while my accelerometer was an MXC6655, support for this accelerometer had been added to the kernel previously through the MXC4005 driver. I even dug up the original messages on the mailing list where this took place. I could see in my lsmod that the MXC4005 driver was, in fact, the active one. This was supposedly a working driver for this model of accelerometer, so, why didn’t it work?

I concluded that I must be some kind of driver issue and a fairly low level problem, so armed with my knowledge so far, I decided to open a bug report. Since this seemed to be not specific to any distribution, I went straight to Linux itself and submitted a bug report on the Kernel bug tracker.

Bug report and further troubleshooting

With my bug report now open, I was very humbled by the immediately helpful responses I received. I’ve had many past experiences in open source communities and forums over the years where my very detailed questions receive no response, or receive incomplete or rude responses which are generally unhelpful.

Working with the kernel.org bug tracker contributors was, in contrast, far more pleasant and helpful than any support experience I can think of, even when working with support departments for major enterprise products.

It was a very humbling experience, and I am definitely glad to know there are so many great people working on the Linux kernel. Everyone I worked with there provided just enough information on what they wanted me to do or test or collect data from, offered more assistance if I needed it, and made me feel like my (honestly, relatively unimportant) bug was something they were going to get to the bottom of.

I will cover some of the basic steps and process that went into the troubleshooting here, but if you want to see the actual dump data and actual exchanges, you can read further on the actual bug report: https://bugzilla.kernel.org/show_bug.cgi?id=218578

The first step was dumping some data from the ACPI tables to a file and extract the accelerometer related information.

# cat /proc/acpi/dsdt > dsdt.dat
# iasl -d dsdt.dat

The above process creates a second file in your working directory, called “dsdt.dsl”, which is a lot more human readable. I proceeded to open that in a text editor and find and extract the accelerometer related information.

It was at this point that someone who read my detailed report asked me an interesting question I hadn’t considered. Essentially, they called me out on saying I was “rebooting” a lot, and asked what I meant by “reboot” and if I had tried a cold start from a powered off state.

Admittedly, this was not something which I’d really ever given any prior thought to. I knew that Windows had a “fast startup” feature which caused it to save some state data so it could boot faster next time. But outside of this fact, it hadn’t really occurred to me that on a modern computer there would be any functional difference between powering it off and “rebooting”. Especially when transitioning between operating systems, like rebooting Windows, and selecting Fedora from a GRUB menu.

To my shock, when I began to test things from a cold start, the accelerometer actually started working. Evidently, this had something to do with why I was finding reports online from other people with the same hardware who said it was working. They likely weren’t trying to do anything as fancy as I was, and were not dual booting these tablets, so they weren’t “rebooting” as much as I was. Anyone who was fully powering down their computer every time they started up next time, would have been blissfully unaware of the issue I was facing. But, because I was constantly testing things by installing and then rebooting straight out of a live environment, or rebooting straight out of Windows into a live USB, I was very often not cold booting the machine. And when I was cold booting the machine, it was usually into a live USB to install a new Linux distribution to test, and with the keyboard attached so I could run the installer… thus, when I did cold boot, I wasn’t trying to rotate the tablet.

With this new information in hand, I continued with the information gathering. I gathered some information to find the DSDT node which is being used on the tablet, under the instruction of the helpful contributor who was now handling my bug ticket.

# ls -l /sys/bus/i2c/devices/
i2c-MXC6655:00 -> ../../../devices/pci0000:00/0000:00:15.0/i2c_designware.0/i2c-0/i2c-MXC6655:00

# cat /sys/bus/i2c/devices/i2c-MXC6655\:00/firmware_node/path 
\_SB_.PCI0.I2C0.ACC0

I also collected information from “acpidump” and “dmesg” which was just simply dumped onto the bug report ticket for further analysis.

The next instructions I was given were to install i2c-tools, which opened up a whole other world of troubleshooting I didn’t know was possible. I was instructed to take some I2C dumps: one of a good working accelerometer state after a cold boot and another after a warm reboot where the accelerometer didn’t work.

i2cdump -y -f -r 0-15 0 0x15 > i2dcump.txt

Even more interesting, I was given a command to reset the accelerometer manually!

i2cset -y -f 0 0x15 0x01 0x10

So, I needed to generate a third dump. After the warm reboot where the accelerometer did not work, and I had generated that dump, I was to reset the accelerometer and take a third dump to show the state afterwards.

To my amazement, the reset command actually brought my dead accelerometer back to life right in front of my eyes, and I took the third i2c dump and attached them all.

After collecting all of this data, the contributor helping me determined that the driver did not always reset the accelerometer chip, and sometimes the chip came up with a bit register set incorrectly and putting the chip in “power-down” mode. The solution seemed simple enough, the driver would be patched to add the reset command to the probe() method of the driver, so when the driver probed the accelerometer, this bit would get reset back to the correct value if it was wrong.

This led me to bring up the possibility of the same thing happening while coming out of a sleep power state (which was also occurring in my testing), and since the same reset was correcting that condition, we would also include a reset of the chip after resume from standby in the patch.

The patch and testing

To my excitement, I soon received a bug ticket update asking me to test an experimental kernel with the new driver included. I had never done anything like this before, but I received these instructions along with a few other links:

Generic Fedora kernel test instructions
=======================================

1. Create a folder to save the kernel rpms into
2. Download the:
    kernel-core-<version>.x86_64.rpm
    kernel-modules-<version>.x86_64.rpm
    kernel-modules-core-<version>.x86_64.rpm
   files from the provided koji link into the created folder
3. From the folder run: "sudo rpm -ivh --oldpackage kernel*.rpm"
4. Remove any manual configuration you've done to work around the bug, such as
   kernel cmdline changes in grub config files, or /etc/modprobe.d/*.conf files
5. Note test kernels are not signed so you need to disable secureboot if you
   have it enabled
5. Reboot, press ESC / F1 / F2 (machine specific) to enter your BIOS setup
   to disable secure-boot if necessary
6. Select the new kernel (should be selected by default) and boot into the new
   kernel
7. Verify you've removed any special kernel commandline options by doing:
   "cat /proc/cmdline" and checking they are not there
8. Test if the bug is now fixed
9. Report the testing-results back in bugzilla

My test kernel was to be kernel-6.7.10-200.bz218578.fc39, and was available to me to download from the Fedora build system. There was also now a mailing list discussion going to work on getting this patch implemented in the kernel code base once I had tested it.

I followed the instructions and installed the experimental kernel, and the problems with my accelerometer seemed to be completely solved! 🙂 The accelerometer worked on cold boots, warm boots, and even when coming off of a sleep state!

At this point, I am not sure which kernel update will have the patched driver… and I know it will take a longer time for the patched kernel to trickle down to other distributions like Ubuntu and Linux Mint, but hopefully in the meantime if someone is having the same problem, they will find something in this write-up helpful, and they’ll know that a patch is on the way… in the meantime, they can always manually reset the accelerometer if they need to.

Many thanks to the contributors who helped with the kernel bug ticket! It was a pleasure working with you. 🙂

Accelerometer orientation problems

There was still one other issue which was unrelated to my bug report ticket. The accelerometer orientation was wrong. When the screen rotated, it was usually upside down from the actual orientation of the tablet for me. Some people said it was off by 90 degrees? I feel like mine was off by 180 degrees. I’m not sure if that was really a difference or if people were misremembering or misspeaking about their angles… regardless… I had done some manual stuff to get this resolved through the course of my troubleshooting, and it led me down some completely different rabbit holes.

I had been told to add a rule to /etc/udev/hwdb.d/ containing the following:

sensor:modalias:acpi:MXC6655*:dmi:*:svnCHUWIInnovationAndTechnology*:pnUBookX:*
 ACCEL_MOUNT_MATRIX= 0, -1, 0; -1, 0, 0; 0, 0, 1

My initial attempts to do this were weirdly unsuccessful. Given the other problems I was having with the accelerometer, this was difficult to troubleshoot for awhile since I was somewhat working on both issues concurrently.

• I did not realize at first that files in /etc/udev/hwdb.d/ must have the “.hwdb” extension. Some other extension, like “.conf” will not work in this location.
• When the information was communicated to me, it was poorly formatted by the website where it was posted, and I did not realize that there should be a single SPACE before ACCEL_MOUNT_MATRIX.

So despite the fact I was copying and pasting this straight from someone who said it worked for them, initially it didn’t for me. It did finally work once I figured out the missing space and file extension issues.

I also learned the proper way to reload this configuration without fully rebooting the system. A lot of the older posts out there do not do this through systemd, so I eventually came across this method which seemed to do the trick.

# systemd-hwdb update && udevadm trigger

This configuration reload process was actually instrumental to me figuring out why the configuration I had wasn’t working, as without the space before ACCEL_MOUNT_MATRIX, I received an error: “Property expected, ignoring record with no properties”. This eventually led me to realize my file was formatted improperly, a fact which was obscured to me before when I was just rebooting to try to apply my changes.

Now that I had this working, and my accelerometer was fully functioning as expected, I wanted to try to get this updated for other people too so that one day with the updated kernel these UBook tablets will just work correctly straight on a fresh install of any distribution.

With the help of the bug tracker contributors, I was led to the actual hwdb file on the systemd GitHub: https://github.com/systemd/systemd/blob/main/hwdb.d/60-sensor.hwdb

To my shock, almost this exact line existed on the hwdb list already. The existing code looked like this:

# Chuwi Ubook X (CWI535)
sensor:modalias:acpi:MXC6655*:dmi*:svnCHUWIInnovationAndTechnology*:pnUBookX:*
 ACCEL_MOUNT_MATRIX=0, -1, 0; -1, 0, 0; 0, 0, -1

Maybe it shouldn’t have, but it actually took a side-by-side comparison in a text editor for me to figure out what was wrong with this.

It was missing a colon!

This led to my first GitHub pull request to a real open source project. I submitted a pull request to systemd to fix the missing colon so this hwdb entry would work for others in the future.

Now, the official code in the systemd codebase is correct and matches what is in my hwdb override file:

# Chuwi Ubook X (CWI535)
sensor:modalias:acpi:MXC6655*:dmi:*:svnCHUWIInnovationAndTechnology*:pnUBookX:*
 ACCEL_MOUNT_MATRIX=0, -1, 0; -1, 0, 0; 0, 0, -1

So, one day future UBook owners won’t have to worry about this anymore.

What does ACCEL_MOUNT_MATRIX actually do?

Before I realized why my configuration file was not working (because I had no output, I could just see there was no change to the behavior) I dove a bit into ACCEL_MOUNT_MATRIX, what it really does, and what the values really mean. I want to elaborate on this a bit here too, as I didn’t find this to be immediately obvious, and in fact, it seems to never really be discussed accompanying the various recommendations I found posted by people to use various values for this.

I found a good authoritative source on this which I wanted to share in this write-up. It comes from the iio-sensory-proxy documentation, and can be found here.

The ACCEL_MOUNT_MATRIX is used to correct accelerometer orientation issues, essentially giving you a way to override the values if the accelerometer is not mounted in the same orientation the software expects. This part is fairly obvious, but wasn’t obvious to me at first was exactly how it works.

In my first callback to high school math classes I’ve had in awhile, I learned that this is essentially using matrix multiplication to adjust the accelerometer values.

So, hopefully this additional information will give some context if you are reading this and need to formulate your own accelerometer mount matrix to correct an accelerometer for which the work has not already been put in to create this.

Once you wrap your head around it, you can see that it’s just some simple math to flip and invert values as needed.

Where my Linux UBook is now

This has been a truly fascinating journey for me, I feel like I barely scratched the surface with this lengthy write-up. It has provided some valuable insights for me into how lower level drivers for these type of devices work, and given me some firsthand experience in how Linux kernel bugs are reported and eventually patched. It has also given me a new appreciation for the incredibly intelligent people who are hanging around the Linux kernel bug tracker with the knowledge to troubleshoot these type of issues at an expert level. If you feel like this write-up was over your head and highly technical, you understand the level of amazement I have at the technical knowledge that goes into these efforts.

I am now comfortably running Fedora 39 on my UBook and I will continue to keep the patched kernel installed and available on my GRUB menu, so I can hopefully continue to use it until the patch goes into the real Fedora 39 kernel mainline. In the meantime, I will continue to experiment with Linux on my tablet.

There are still a few things about the Linux experience on this tablet I am not fully satisfied with yet, and I feel like this will not be the last technical write-up on my journey to solve my problems.

A few more outstanding things I want to work on:

• I would like to get a graphical boot loader working with touch screen support, so that I can select my Windows or Linux boot using only the touch screen. I have been experimenting with rEFInd, but their touch support does not currently seem to work with the UBook touch screen. This may be my next “bug report rabbit hole” after I find some time for further testing.
• I am not entirely satisfied with the Intel graphics performance on Fedora. For most uses it is good enough, but I noticed that 4K and 1440P YouTube videos are struggling on my Fedora install, where they playback effortlessly in Windows. It sounds like the Intel graphics drivers may ship with some “not optimized for performance” defaults, even on bleeding edge kernels. My next stop will be threads like this one which make some suggestions I haven’t tried yet.
• It was brought to my attention that the built-in webcams don’t work on Linux yet, and I have confirmed this to be the case as well. There is an existing StackExchange post about this from another UBook user, so far with no replies. It looks like the webcams are Intel IPU3 CIO2 devices, and they may not work the same way as other webcam video sensors (they may not output normal RGB or YUV data, and it may be a raw Bayer sensor). I might look into this further too.

All in all, these are minor things to me, and I will be using Linux on a more regular basis on this tablet now that I have the accelerometer working.

I’ll likely continue to run Fedora 39. I like the GNOME interface on this tablet, even though I am not very fond of some of their UI decisions when I am running it on a real desktop. I think GNOME is the best “desktop experience” out there for a Linux tablet right now.

KDE Plasma Mobile was also brought to my attention, and I have installed this as well, so that I can toggle back and forth between this and GNOME on my login screen. So far, KDE Plasma Mobile seems to be even more tablet optimized than GNOME. To me though, the interface almost feels a bit “too” mobile… it feels more like using an Android tablet than a Linux one. GNOME may be a bit better suited to my tastes, but there are a few things I like on KDE Plasma slightly better, like I feel that I can type more accurately on their on-screen keyboard.

I will continue experimenting and hopefully will have more knowledge to share in another write-up in the future. 🙂

In 2021, an AT&T landline price increase finally gave my grandma the push she needed to get rid of her landline phone service. I have been encouraging my family to use their Google Voice lines for many years, but some of them have still held on to their expensive landline service. A hangup for my grandma was not wanting to lose her primary phone number, so I set off to see about porting it to Google Voice.

Google Voice, for some reason, will not port a landline number directly. I came across some other articles online, like this one from The Cord Cutting Report, which I found helpful throughout my process. So, I thought I’d document my experience for the future reference of myself and anyone else who may find it useful.

TracFone as a number porting intermediary.

Numerous guides I’d read online suggested using a prepaid cell phone carrier, such as Ting, to port the number away from the landline service. This process would transition the phone number into a mobile number, which Google Voice is willing and able to port over to their service.

I decided to use TracFone, since I have used them personally for many years, as has most of my family. As a result of my long time as a customer, I had an old Android phone laying around from a previous TracFone service term, and was able to get it activated on the network again – so I did not even have to buy a burner phone, I already had it!

I’ve read that others have experienced problems with their number porting due to information not matching up on the two accounts. It seems that things like the billing zip code on the credit card used to order the service, and other factors can impact the process. So, to attempt to minimize any such issues, I added my old phone to my grandma’s TracFone account, and we ordered the service using her credit card. This way, all of the billing and account information will match her AT&T landline service.

I began the process on a Thursday night, knowing it may take 1-2 business days, not knowing whether it would be done before the weekend or not. But, there was no rush here. I’d been informed through my research that it was a good idea to wait at least 1 full week between porting the number to TracFone and trying to port it again, so with this intention in mind, nobody was in any hurry.

The Porting Process – Initial Issues

Having personally never ported a number before, I wasn’t totally familiar with the process and what it would entail. I began the process on TracFone’s website, which asked me for the AT&T account number and password\PIN for the account I wanted to port the number from.

The account number could be found on the top right corner of the AT&T landline bill.

It seemed completely clear, although there was some awkward spacing in the information. For the sake of this example so I can provide a workable example with a non-real account number, let’s say her phone number was (111) 222-3456. And let’s say the account PIN was 7654.

The information appearing as “Account Number” on the AT&T bill was formatted like this: 111 222-3456 765 4

I tried all possible combinations of these numbers on TracFone’s website, but it said everything I entered was an invalid account number. I came across this Reddit thread from someone else who had the same issue. The thread seemed to conclude that the account number would be 13 digits, so from our example, I assumed the correct account number would be 1112223456765. The thread noted it was necessary to select “Other” as the carrier, not “AT&T” because the account number was still not a “valid” AT&T account number, according to the form.

I figured I could call TracFone support, but I also figured there was no harm in trying this, and if it didn’t work I could fall back to calling support. So, I went ahead and did as suggested, entering the account number as 1112223456765 and the PIN as 7654.

The Wait Begins

After entering the information, TracFone appeared to accept the order and begin the porting process. They provided the following guidance:

For kicks, I tried to activate the phone several hours later, and unsurprisingly, the activation was not successful. The wait was now on to see how many days \ business days the transfer would take, and if it would even be successful at all.

Unexpected Issues

Unfortunately, there was a hangup in my plan. Tracfone called us the next day to notify us that the phone we were trying to activate was too old, and no longer supported by the network. I was somewhat surprised, considering I still know at least one person actively using the same model phone on Tracfone’s network, but since the temporary phone I had was a 3G phone, they probably are no longer activating 3G phones since that network is in the process of being decommissioned by major carriers, like AT&T.

I really didn’t want to buy a phone for the sole purpose of using for a week, so I started asking around, and was fortunate to find a friend with an old 4G unlocked phone they were no longer using. I was able to borrow their phone and use a very cheap TracFone BYOD SIM card to attempt to activate it on TracFone’s network.

The process of activating the second phone was difficult the first time, the first agent I called was unable to find the service card we had paid for on the previous phone, and told me that the account number I had from AT&T was invalid for the number port. (This turned out to not be true – the information outlined above IS correct.)

I called back a second time the next day, after calling AT&T to verify the account number, and got a different TracFone rep who was able to overcome all of the problems the first rep couldn’t. Finally, the transfer process was underway! I was told it would take 2 days to complete the porting process, since it was a landline. It sounded like they would have to actually communicate with AT&T via email and send over documentation, it would not be a quick automated process (maybe this is why Google refuses to do it!).

Successful TracFone Port!

After two days, as promised, the number was ported and I was able to activate the phone on TracFone’s network. I made a test call to myself and confirmed it came from the old landline number.

Various articles and forum threads I’d read online suggested that I should wait 1 week before trying to port the number again. So, I decided to wait a little extra. The port completed on a Wednesday, and I decided to do the second port the following Sunday, when I could go over to Grandma’s house and finish setting up her Obi200 box.

Porting to Google

The port to Google was a fairly straightforward process overall, but a lot of the information I’d found online concerning how to port out of TracFone had been incorrect.

I began here, on this Google KB post which provides the link to the page to start the number porting process.

The first step was to enter the phone number and check portability, this was where we failed before, since Google did not support porting the AT&T landline. This time, success! Google said the number was eligible for porting. Once on the next screen, they provide the following terms and details:

The next step was to fill out contact information for the phone number being ported (the billing address and details on the TracFone account). Note that the carrier shows up as Verizon, I was expecting this, since I used the Verizon compatible BYOD SIM.

This was where the slight issues began. Every piece of information I found online, including this article from Best Cellular, stated that the “Account Number” for a TracFone BYOD device was the last 15 digits of the SIM card. As far as the 4 digit PIN, information I found online varied from “TracFone doesn’t use PINs, so you should enter 0000” to “TracFone doesn’t use PINs, so you should enter any 4 digit number”. I decided to enter a 4 digit security PIN I knew existed on the account.

Unfortunately, the port request was immediately rejected due to a bad account number. I was provided the option to correct the account number, but didn’t know what the right information was. I really was not looking forward to calling TracFone and asking them how to port away the number they’d just ported in a week earlier, but I decided to give it a shot.

Fortunately, the agent I got at the TracFone number porting department was very helpful, and didn’t seem to care at all about what I was doing. They initially thought I was right to be using the last 15 digits of the SIM card too, but then found another account number in the system that I didn’t have. They provided it to me, and I entered it in the Google form, along with the 4 digit account security PIN. This time, the port was accepted!

I was disappointed that it was going to take another 24 hours, I thought the port would be fairly immediate now that it was a mobile number. I’m not sure if the delay was normal, because it was a landline, or because I made a mistake on the form the first time. Either way, Google was very timely and completed the port request exactly when they said they would. The next day, we received an email notifying us it was complete!

Closing Thoughts

This was my first time ever porting a phone number in any capacity, and I was trying to do something somewhat unsupported… All in all, this process was as easy as I could have asked for. There were certainly some snags along the way, which were learning experiences for me, but I would definitely do this again in the future if someone else in my family asks for assistance getting rid of their landline. Hopefully someone else out there will also find this information useful if you are trying to do the same process, or wondering what will be involved and how hard it will be. Happy porting!

CKEditor 5 is a WYSIWYG text editor that can be used for a variety of purposes, from creating your own Google Docs type of site to creating your own WordPress knock-off platform.

I recently wanted to use this editor, but was disappointed with the lack of features in the default builds. It doesn’t even have underlining. Evidently the official stance of the developers is that you should build your own and they won’t provide a full build anymore like they did for CKEditor 4.

CKEditor provides some detailed build instructions on their documentation, but as someone who is not a Javascript developer and has never used Node before, I found the process a bit intimidating at first. So I am writing this guide up for my own future reference when I need to update my build, and also to hopefully help someone else who is in the same situation by explaining what I feel isn’t well explained to someone who’s completely new to NPM.

The Basics – Starting Your Build

First you will need NPM installed as well as Yarn. For me on Debian 10 the package name for Yarn was not immediately intuitive and the command was different than just “yarn”.

On Debian 10 my dependencies were:
# apt-get install npm yarnpkg git

Once these are installed you can simply clone the Git repository. I didn’t plan on keeping this server long term so I’m just doing it the lazy way on to a temporary VM I am going to delete when I have my final build. This isn’t the best way if you are developing your own stuff, but if you are like me and you just want a build that CKEditor won’t provide, you can just use a temp environment on a throwaway VM like I did. I had no desire to junk up my live server or even my desktop with all this NPM stuff I will not likely use again anytime soon.

For the purposes of this project I am starting with a “Classic” editor as that’s closest to what I want.

# git clone -b stable https://github.com/ckeditor/ckeditor5-build-classic.git
# cd ckeditor5-build-classic
# git remote add upstream https://github.com/ckeditor/ckeditor5-build-classic.git

Finding The Plugins You Want

The plugins you want can all be located on this page of the official documentation. I simply went through each option on the sidebar to see which plugins I might want.

Some of these are already included in the build, which you can discern by reading the build file located in src/ckeditor.js on your VM.

For the purposes of my build, I am adding Alignment, Strikethrough, Underline, Subscript, Superscript, Code, Highlight, HorizontalLine, RemoveFormat, Base64UploadAdapter, and ImageResize.

Installing Plugins

To install your desired plugin, there are 3 steps.

1. Install the NPM package. The directions for this are provided on the plugin page on the documentation. Here are the NPM installs I ran to install the plugins I wanted:

# npm install --save @ckeditor/ckeditor5-alignment
# npm install --save @ckeditor/ckeditor5-highlight
# npm install --save @ckeditor/ckeditor5-horizontal-line
# npm install --save @ckeditor/ckeditor5-remove-format
# npm install --save @ckeditor/ckeditor5-upload

At a glance, you might notice these plugins do not match what I stated I wanted to add above. This is because you may see that some plugins contain several features, not all of which must be imported. For example, Base64UploadAdapter is one feature of ckeditor5-upload, there are other features which I haven’t imported such as SimpleUploadAdapter.

You can discern which features are part of which plugin from the plugin’s documentation page. Each one has a link to a page containing more information about the feature.

2. Edit src/ckeditor.js to contain an import line for each plugin feature that you wish to import. For the purposes of my build, I added these import lines below the default ones.

import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment'
import Strikethrough from '@ckeditor/ckeditor5-basic-styles/src/strikethrough';
import Underline from '@ckeditor/ckeditor5-basic-styles/src/underline';
import Subscript from '@ckeditor/ckeditor5-basic-styles/src/subscript';
import Superscript from '@ckeditor/ckeditor5-basic-styles/src/superscript';
import Code from '@ckeditor/ckeditor5-basic-styles/src/code';
import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight';
import HorizontalLine from '@ckeditor/ckeditor5-horizontal-line/src/horizontalline';
import RemoveFormat from '@ckeditor/ckeditor5-remove-format/src/removeformat';
import Base64UploadAdapter from '@ckeditor/ckeditor5-upload/src/adapters/base64uploadadapter';
import ImageResize from '@ckeditor/ckeditor5-image/src/imageresize';

As a newbie to NPM, I wasn’t 100% sure how to determine exactly what should go here at first. Since I for example ran “npm install –save @ckeditor/ckeditor5-upload” how do I determine the remainder of the string to import the feature?

The best way I found is to click through to the GitHub page for the plugin, and navigate into the “src” folder. There, you will see .js files, and you simply need to put the path to the .js file, minus the extension.

3. Add a line for each plugin in the ClassicEditor.builtinPlugins section of src/ckeditor.js. Unless you do this the plugin won’t actually be built into your build, which afterall is the goal.

Once again, I came across some ambiguity here. Where do the names of the plugins come from and how can I make sure I have the capitazliation correct and everything?

I copied the exact name as displayed on the documentation page for the plugin, it seemed to work correctly 100% of the time.

Some caution is needed here as some plugins contain dashes in the NPM package but the plugin itself doesn’t contain a dash. For example “@ckeditor/ckeditor5-horizontal-line” the plugin name is “HorizontalLine”.

On the Horizontal Line page of documentation, it says “See the Horizontal line feature guide and the HorizontalLine plugin documentation.” This is where I was sourcing my exact spellings and it was working reliably.

Here’s what my additional lines looked like:

        Alignment,
        Strikethrough,
        Underline,
        Subscript,
        Superscript,
        Code,
        Highlight,
        HorizontalLine,
        RemoveFormat,
        Base64UploadAdapter,
        ImageResize,

4. Add your desired plugin to the “toolbar:” section of the ClassicEditor.defaultConfig in src/ckeditor.js.

Once again some ambiguity here. I used the lowercase version of the plugin name from the section above in step 3. This seemed to work 100% of the time.

By the way, you can use the pipe ‘|’, in the toolbar section to add spacers to the toolbar.

I moved some stuff around so here is what my whole toolbar section ended up looking like:

        toolbar: {
                items: [
                        'heading',
                        'removeformat',
                        'horizontalline',
                        '|',
                        'alignment',
                        'bold',
                        'italic',
                        'underline',
                        '|',
                        'strikethrough',
                        'subscript',
                        'superscript',
                        '|',
                        'link',
                        'bulletedList',
                        'numberedList',
                        '|',
                        'highlight',
                        'indent',
                        'outdent',
                        '|',
                        'imageUpload',
                        'mediaEmbed',
                        '|',
                        'code',
                        'blockQuote',
                        'insertTable',
                        '|',
                        'undo',
                        'redo'
                ]
        },

A Note About Some Dumb (In My Opinion) Defaults

CKEditor comes bundled with a few things which I removed for the purposes of my build.

Firstly it comes bundled with CKFinder and its associated UploadAdapter. Are far as I can tell, this does not function without a server side script I don’t care to invest time investigating, so I’m removing these from my build.

Additionally I am removing EasyImage because I have no plans to use cloud services.

To remove these items, I’m simply commenting the imports out and the plugin declarations in builtinPlugins in my src/ckeditor.js before finishing my build.

Out of the box, the image upload features of the editor do not work unless you put in some elbow grease. For now I am implementing Base64 image uploading so I don’t have to mess with a server side handler and filesystem permissions issues that can come along with uploading files. We’ll see how this works for me in my use case long term, I may switch to the Simple Upload Adapter and write a server side handler in the future.

I personally think CK Editor should just include the Base64 uploader by default so that the features work out of the box instead of this CKFinder plugin that doesn’t work without additional dependencies.

Finishing Your Build

Once you have added all of the customizations to your build, you can compile it with the Yarn tool you installed.

Although the official documentation suggests the command is “yarn”, on my Debian 10 system, it was “yarnpkg”.

So to finish my build I ran:

# yarnpkg build

Once it’s finished, the completed file is located in build/ckeditor.js. This file can be used as a drop-in replacement for any other downloadable build direct from CKEditor, and it should contain your new features.

I found I could run this build over and over as I refined my source file and I didn’t have any problems, it just overwrote my build file with a new one.

There ya go! I hope this guide simplifies someone’s project. 🙂