My 13-year open source journey has been shaped by several key ideas that have helped me better understand the world I am now contributing to. Even years later, I sometimes still find myself thinking about, linking back to, and sharing many of these ideas.

Learning how to ask

Back in 2013, as I was learning about the Arduino and what it could do, my searches led me more and more to the questions and answers posted on Stack Overflow. While I didn’t know it at the time, my timing was almost perfect, as the site was just hitting its peak.

Shortly after discovering StackOverflow, I began finding questions that weren’t yet answered, leading me down the path of learning to write my own questions and learning how to learn along the way.

Learning how to learn for yourself is something I later found to be a key aspect of working in any environment, not just software. Learning to spend time trying to solve the problem with the resources you have available — before involving someone else for help — was an excellent early skill for me. Not only is it a way to practice independent problem solving, but it also shows respect for other people’s time by providing them with more information about what you have already tried - skipping the back-and-forth of basic troubleshooting steps.

The resources below are a great start for learning the skills and social norms of communication in online spaces:

• Help Vampires: A Spotter’s Guide (2006)

• xyproblem.info (2014)

• Never Just (2025)

These sites also extend this idea of online communication norms into more chat-oriented spaces:

• Don’t Ask To Ask (2019)

• No Hello (2022)

• [Bonus] StackOverflow’s official “How do I ask a good question?” guide

If you enjoy websites that are solely built to make a single point, you may also enjoy this curse-word-laden series of websites dedicated to various opinions on how websites should be built.

Learning Git

Git helps you manage different versions of your code. Instead of repeatedly saving different versions of the same file as you make changes, Git allows you to save your progress as snapshots (commits) and essentially time-travel through the history of your project. This provides nearly limitless ability to undo, experiment, and try new things while allowing you to go back to the last known-working version if you ever need to.

Version control tools like Git are widely used, especially for software. While there are many, many resources for learning git out there, here are the ones I would recommend:

• Oh My Git (interactive game)

• The Git Book (book)

• Learn Git on Codecademy (interactive lesson, now paid but possibly doable with a free trial)

Once you understand the basic concepts of git version control, you can use them in different ways depending on what fits your particular project the best:

• A Successful Git Branching Model

• Github Flow

• If you think you’ve made a huge mistake, there’s always ohshitgit.com.

What is Free and Open Source Software?

While I was learning to build things using Arduino, I found nearly all of my learning resources (Stack Overflow, tutorials, official documentation, etc) freely available online. I later learned that having whole communities of people building and sharing knowledge and tools openly online was quite common.

In the software world, this movement is called Free and Open Source Software (FOSS) and represents the idea that everyone should have the same basic rights to the software that they use. The historical context of how this movement came to be is also worth understanding because these ideas of software freedom have come up again and again in many different ways throughout my later experiences.

Here are some of my favorite resources for getting to know some of the history and principles behind software freedom:

• Demystifying Open Source, Free Software, & 46 Years of a Legacy (video, watch from 13:00-30:00 if you are in a hurry)

• What is Free Software

• The GNU Philosophy page

• “How I coined the term ‘open source’”

• GNU: “Why Open Source Misses the Point of Free Software”

The role of coding

As I started doing more and more coding projects, I began to learn the importance of good design and good practices when it comes to the code that gets written. While code may be a very structured, logical thing, there is still a surprising amount of creativity and choice. A software developer can choose from several different approaches, code structures, and data sources to build their solution, and those choices will either help the project grow, or slow you down as the project grows.

At the same time, I also began to see just how much time is spent doing or thinking about things other than writing code. In other words, you could have the most well-built code ever, but if it isn’t a good fit for the project you are contributing to, your code may not make it into the project. Essentially, once things grow beyond a simple solo project, talking to people (planning code changes, dividing work, communicating changes to users, etc) becomes another important step in the process alongside writing quality code in the first place.

To take things a step further, knowing when not to code is also important. If a project does not have a defined scope and says yes to every new contribution, the project will eventually trend towards turning into “everything for everyone”. Saying “no” is arguably even more important than saying “yes”. Without “no” as a counterbalance to define the other side of the line, “yes” can rapidly lose its meaning just like the feeling of happiness can start to lose its meaning in the absence of sadness.

If you’d like to understand more about the work that goes into creating and maintaining software, here are some articles to get you started:

• The reality of long-term software maintenance from the maintainer’s perspective

• Habits of great software engineers

• The glue is the work

• Pretotyping (book, 1st edition PDF, 2nd edition pdf)

Building systems

Beyond just having a specific purpose and scope, it’s important to understand how your projects fit into the larger world and the impacts they have (intentional or otherwise).

Many years ago, I would have thought of “systems” as this big, abstract, intangible concept. I now realize that my own code is a kind of system - an externalized form of some task that needs to be done.

Being able to hand off tasks to a system or process can help solve any number of needs, such as:

• Building a website to communicate your business or personal projects.
• Setting a calendar reminder to remember to change your air filters.
• Storing your keys in a sensible place to prevent losing them when you are trying to leave the house.

Each of these examples is a miniature system that offloads some beneficial process, setting it up to happen automatically. These systems can then be combined, such as adding a contact email to your website, making the system more useful for its intended purpose. Once you start noticing and building upon to the systems around you, it can be so rewarding that it’s hard to stop!

Despite how fun and rewarding building small personal systems can be, larger systems carry far more risk. Think about the last time you interacted with a frustrating system. Maybe it was a printer, or a ticketing app, or your landlord’s laundry machine. Maybe it felt like that system was forcing some arbitrary rule on you that made no sense. To avoid systematically frustrating people (or worse), larger systems require much more time and planning. If you look, sometimes you’ll even find systems that have built-in feedback mechanisms to allow new issues to be corrected early. This is especially common with systems built in the open.

If systems sound like an interesting concept to you, you may like these articles:

• When Databases Get to Define Family

• Adversarial Interoperability

• How Policy Becomes Code

If you like learning about fun edge cases systems can have, I’d also suggest checking out this video about timezones and this article about names.

There’s also this amazing Public Service Announcement from the Norwegian government.

The humans behind the systems

Personal systems like a house can be a fun way to get started, but using a system someone else built is my personal favorite. Collaborating and reusing pieces that others have built helps you accomplish more together than you can on your own. It’s also a great way to cross paths with different people who are also making a difference and have a passion for sharing their work with the world.

Mister Rogers was right when he said “look for the helpers” - if you want to find out what really keeps a community healthy, look for the people.

Here are just a few articles with interesting perspectives on the human influences that guide the systems we build:

• The Stories That Bind Us

• Paying people to work on open source is good actually

• I Can’t Believe How Few People it Takes. (video)

• Don’t Get Distracted (article and video)

• “When is Enough Enough? -or- When Enough is Enough” (video)

• Open Source Gave Me Everything Until I Had Nothing Left to Give

• Death by a Thousand Slops

• Eternal September

How to contribute

If you are just getting started contributing to Open Source or any other field of Open Work, here’s my advice:

1. Don’t forget the people behind the systems - look past the code
2. Think about the “why” - both the community’s and your own
3. Give it a try - do the best you can with the resources available, and ask for help or a quick pointer if you need it
4. Leave things better for the next person - document what you have done in the appropriate places (issues, docs, your own blog, etc) so that someone else can learn from you

Here are some resources for getting started:

• “Open Source Isn’t Scary - Here’s How to Start Today” (article, video)

• Open Source Guide

There are so many more resources available online than I can even begin to link here. These are just the few that stand out to me from the past 13 years of my own tinkering, learning, building, failing, and collaborating. I hope these resources illuminate enough of my journey for someone else to follow the trail and take it in their own direction.

Just remember to look for the people behind the systems. The helpers.

These emails were legitimate. The alarming part was that they were notifying me that new owners had been added to Google Search Console Dashboard for one of my subdomains.

This was not an action I had taken.

This is the story of how my subdomain got compromised and had its content replaced with what appeared to be an Amazon lookalike page acting as a login front for a foreign gambling website. After all, what else would make a scarier Halloween blog post than talking about a surprise website takeover?

Damage control

Within a minute of receiving the emails, I began investigating the extent of the damage while also trying to prevent it from spreading.

My first step was to look up Google support articles for unauthorized new owners in Google search console, however this only confirmed what I already knew: someone else was able to control the content of my subdomain.

The next 30-60 min was a bit of a blur as I jumped between trying to report the issue to Google (probably overkill), confirming my DNS was unmodified, and archiving the hacked content to see what I could learn both in the moment and at a later date. Overall the process was pretty haphazard as I was largely figuring things out as I went. Was reporting my own subdomain as spam going to create issues for me later? No clue!

As I investigated deeper, all the evidence started to point to this being an isolated incident. There was nothing suspicious about the DNS records, I had no indications that any of my other domains had been affected, and the compromised page did not seem to be anything more than an impersonal, automated, and unsophisticated attempt to farm a legitimate domain for its SEO value. Things were definitely getting less scary the more I learned.

So what happened?

My “pro” tier GitHub Student Developer account had recently expired. When this happened, I made sure to review what I was using and adjust my usage to fall within the free tier limits in advance. I was aware that I was likely making use of several GitHub pages websites hosted from private repositories, but beyond the obvious “you will lose this perk,” I was never able to find clear guidance throughout the documentation surrounding what exactly would happen to the sites (or their repositories) when my pro status lapsed. This was compounded by the frustration of seeing metrics pages and other, much clearer guidance surrounding my usage of other paid resources like github actions compute time.

By the time I reviewed the github pages site for the affected subdomain, I had already migrated several others, and this one didn’t seem especially worth the effort. The subdomain in question was called movies and it hosted a simple HTML redirect to a private address on my home network - essentially a convenience shortcut to a small web application to allow my family to vote on and propose movies they wanted to watch.

As GitHub support later confirmed:

When a user account moves from Pro to Free, any GitHub Pages sites that publish from private repositories are taken offline, and the custom domain is detached from that repo. If DNS records for that domain continue to point at GitHub Pages, someone else can add that domain to their Pages site until you verify ownership. Archiving a repository by itself does not detach the custom domain or make it available; the downgrade is the event that causes the detach.

The support rep mentioned domain verification as a mitigation strategy, but I did not have this set up at the time I found out my site had been changed.

While I have no way of confirming the exact timing of the changes to the page, I suspect that it happened shortly before the attackers tried to use HTML tags to claim Google search console ownership over it. That said, it could also have happened anytime in the prior year based on the date of the last internet archive capture for the subdomain and my records of when I migrated my other pages-hosted sites.

Remediation and Lessons Learned

Since the affected domain was really not in use anyway, I resolved the issue by revoking the DNS entries for it entirely and confirming that the unauthorized Search Console users have been removed. Per GitHub’s recommendation, I also verified ownership of all of my domains to ensure that they are protected from a takeover in the future.

Overall the impact of this takeover ended up being quite minimal for a few reasons: the site was not and had never really been in especially active use and had essentially no reputation to begin with, any impacts to search engine ranking were likely isolated to that subdomain, and the time it took me to respond once I saw the emails likely meant that there was limited opportunity to spread additional harm.

But I learned a critical lesson: It’s important to be thorough when making changes to anything under your name. Even though I didn’t see this domain and its redirect as particularly important at the time, I realized how important it actually was after someone tried to use it to improve the reputation of their sketchy gambling site. Because I was several domains into performing a repetitive domain migration away from github pages at the time, it was easy to choose to ignore this one and assume GitHub would just stop serving it. However, if I had spent a few minutes removing the DNS entries for the site in that moment, I could have saved myself the several hours to took overall to remediate the issue.

Recommendations for GitHub

This issue potentially affects GitHub users who:

• are on a paid plan that is close to expiring
• have github pages sites backed by private repos
• have custom domains attached to those pages sites
• do not have verification configured for those domains

This is pretty specific list; however, it may include a significant number of people due to the scale and popularity of GitHub among many developers, especially due to their free pages hosting. If the total user count is large enough, this could still affect a significant number of people. The near-silent domain detachment upon downgrade also makes it hard to know whether this has happened to you until your domain becomes the subject of unauthorized modifications. In my opinion, GitHub could do more to at least provide more documentation to their users to ensure they are aware of this particular pitfall of downgrading to a free account.

The easiest suggestion GitHub could implement is to include a mention of this in their existing documentation. There is already a page with information about securing your custom domains, but that page notably leaves out any specific reasons why a domain might become detached. Having a list of several examples - especially ones that require no explicit action from the affected person - would help more people understand that risks may be present even if they don’t specifically take any actions regarding domains.

Another way that GitHub could prevent this attack chain could be to provide a usage dashboard for their paid customers that shows all private-repository-backed github pages sites alongside the other usage metrics. While it is more work than updating a documentation page, it seems like GitHub already has the ability to detect this type of usage because they automatically disconnect domains on downgrade in the first place.

However, a more effective and proactive solution would be to for GitHub to try and detect whether a customer meets the criteria listed above and more proactively warn them. This would be a great add-on to the documentation and dashboard improvements and could take a number of forms, such as:

• An automatic email sent to the customer some time prior to when their account downgrades to the free tier. This could warn people that another github user may be able to host content on their domain and give clear advice to change the DNS entries or verify their domain.
• Keeping the domain attached but serving site visitors an error page. This page could be designed like the 404/”no github pages site here” page, but adapted to indicate the site is unavailable for policy reasons, with a link to the documentation.

Conclusion

While I think there are ways GitHub could have made this issue and its consequences more visible to me, the subdomain compromise was still largely on me. I wanted to share this story because its a good reminder that security incidents can happen to everyone and there should be no shame in admitting that it happened to you.

Incidents like these, especially when they are relatively minor and from relatively unsophisticated attackers, can also be helpful reminders for where to improve. No person is perfect, especially not all the time, and being able to learn from the mistakes others make is how we can all be more aware of our weaknesses and take steps to protect ourselves and those around us.

Concept2 is a fitness equipment manufacturer that makes indoor rowing machines and other equipment for the sport of rowing. Their machines are considered to be the standard that many rowing clubs use for off-the-water fitness testing.

Why am I looking into the format their machines use to transmit timestamps? Well, because I have experience in the world of rowing, I like taking things apart, I learned that Concept2 has publicly-available communications specifications (among other documentation), and because I have been thinking about open software in the context of rowing even prior to my previous blog post on the subject.

While this information isn’t exactly new (one concept2 forum post about it is from 2015), it seems like the core information was a little buried, especially from the perspective of past-me, who hasn’t developed software for Concept2 machines before. I want to use this blog post as an opportunity to clearly explain what I have since learned about this date format, as well as share a diagram that I have made that really helped me understand it.

Note that this article talks a lot about binary numbers (using terms like bits and bytes), and a basic understanding of these terms is assumed.

A Sea of Confusion

While the details of how bluetooth organizes data for transmitting between devices is way beyond the scope of this post, it is important to know a few things.

The specific Bluetooth Low Energy profile that Concept2 uses for communicating is GATT (which stands for Generic Attribute). This profile uses little-endian order to transmit data. Essentially what this means is that if a number is bigger than 255 (the maximum value that can be stored in one byte of data), it needs to use multiple bytes to transmit that number. These bytes can either be sent with the byte representing the “smallest” or “least significant” or “little end” of the multi-byte sequence first, or it can be sent last (meaning the big end gets sent first). This is where terms like MSB/LSB (Most/Least Significant Byte), Low/high bytes, and big/little endian come from. Using little-endian is less common for communicating between devices (network applications often use big-endian order), however the most important thing is to be consistent on both ends of the communication so data does not get garbled.

Notice how this information is coming from various Bluetooth specification documents, not Concept2. By relying on existing open standards (Bluetooth Low Energy, GATT, etc), Concept2 can enable their devices to “speak the same language” as any number of phones, computers, and other devices that are also built to use these standards. Using open standards also makes their technical documentation a lot simpler, since they don’t have to repeat information that is already defined in other specifications. However, from the perspective of a beginner who was new to developing software that relies on Bluetooth, this did slow down my ability to find the information I needed.

The Concept2 Timestamp Format

In their official specification documents, Concept2 simply refers to this timestamp as:

Log Entry Date Lo,
Log Entry Date Hi,
Log Entry Time Lo,
Log Entry Time Hi,

The Lo and Hi parts of this refer to the least and most significant bytes of each 2-byte sequence, for a total of 4 bytes of data.

Upon some investigation, and after much testing and sanity-checking it seems like the data in these 4 date/time bytes is represented in the following way:

This seems to be confirmed by the 2015 forum post, which refers to the date encoding scheme as a modified version of Binary-coded decimal (BCD). This encoding is helpful because it is both relatively simple and also quite compact, allowing date and time information to be represented with minimal space, especially given that the GATT Bluetooth profile is limited to 20 bytes of data in each transmission.

This date format breaks down into the following components:

• Log Entry Date Lo: Day (lowest 4 of 5 bits), Month (4 bits)
• Log Entry Date Hi: Year (as a number of years since year 2000, 7 bits), Day (highest bit)
• Log Entry Time Lo: Minutes
• Log Entry Time Hi: Hours

As you can see, the time component of this timestamp is a pretty simple 1-to-1 mapping where minutes and Hours each get represented by full byte of data. However, with three pieces of information (year, month, and day) to convey in only 2 bytes, the date portion gets a little more complicated due to needing to draw different bit boundaries that can accommodate all possible date values. For example, if only 4 bits were used for the day, the largest day that could be represented would be the 16th of each month.

Growing a Community

When onboarding new contributors into a community, it is easy to forget that newcomers are starting from a place of near-zero context about the project. This can create additional points of friction that can have an outsized impact on newer contributors. Small pieces of information that is missing from key documents like this may seem inconsequential to developers who have already learned the format, but missing information like this can disproportionately impact newer contributors in ways that vary between the inconvenience of a small papercut all the way to a seemingly insurmountable obstacle.

As I wrote about in my previous blog post about the sport of rowing, rowing is already a sport with a strong sense of community among its athletes, as well as the seeds of openness in the form of Concept2’s public specifications documents. By working to create more software-oriented community spaces within the sport, I hope to help create and support more communities that encourage developers to come together, learn from each other and build amazing community-first software that genuinely improves the sport.

Consider this post a kind of “Cursed Knowledge” compendium if you will. I will leave it up to you whether this is a helpful guide, or a list of reasons to run away from any task involving merging gigabytes of video files together.

How it started

Last summer, I had the opportunity to help run several events as part of my internship with the Fedora Project. These included virtual events such as both the Fedora 40 and 41 Release Parties as well as Fedora’s Week of Diversity event. I also attended Flock to Fedora 2024 and gave a short talk on my role and some of the other projects I’d been up to throughout my internship (after some A/V failures).

While helping run these events, I began creating many tools (such as matrix bots) to help make the process easier. My goal was to speed up the existing process by developing some scripts that would help accelerate the existing process and get videos out to the community faster after the event.

Doing it the wrong way, but faster

1. Imperfect cuts

Isn’t all recorded video simply a series of photos taken in rapid succession? Surely you can just split the video between any two frames right?

Yes, that was a joke.

Modern video formats take advantage of whats known as “interframe compression” to save space. As you capture video faster and faster (i.e. a higher frame rate), less time as passed between each frame, meaning less things have likely moved or changed from one frame to the next.

Instead of storing every frame, it’s possible to save quite a lot of space by only storing full frames occasionally and encoding the in-between frames as “differences” or “transformations” of those full frames to create the next frame on the fly. While this is great for storage efficiency, this kind of frame compression means you can’t just chop a video wherever you want. These “difference” frames need to be processed relative to what is around them to make any sense.

Because early versions of the script were making cuts in a way that rounded to the nearest full frame, cuts would frequently be too early or too late by up to a couple of seconds.

Of course, while it is possible to decode every frame from the video in full quality, remove the ones you don’t want, and then re-encode the video from that new set of frames, this can often take longer to process a video than that video’s duration. When you’re processing video from multiple days worth of several concurrent live streams, having to spend more time than it would take to “watch” every single livestream is pretty inefficient.

The solution? The LosslessCut video editing tool had a feature called “smart cut” that is able to intelligently handle these kinds of cuts, only re-encoding the minimum possible amount and being both a LOT faster than a full re-encoding operation, and a lot more accurate than existing “fast cut” operations.

2. Video Format consistency

Surely just having all the videos in the same format will work better right?

Right?

Depends on your definition of “the same.”

Early on in the development of these scripts, I thought Google’s new webm video format would be the easiest to work with and keep things simple. The tools for downloading live streams from YouTube even supported selecting this format, how perfect!

It was not perfect.

As it turns out, Google probably knows a lot more about video formats than I do. I had assumed Google was offering up the same video in a variety of different formats for convenience; in reality they were trying to save as much space as possible by offering different quality levels of video in different formats.

By blindly assuming that the format I had chosen was the best available quality as everything else, I was inadvertently including lower-resolution content in the final edits, causing the quality to change mid-video.

Thankfully, the YouTube comments let me know almost immediately.

Ultimately the solution was to use the highest available quality (which usually ended up in a mix of mkv, mp4, or webm format) and ensure that the formats matched after the fact.

3. High Pitched Voices (but only some of them)

Then came the weirdest bug of all. As the talks started to go live and people began watching, they noticed that voices seemed pitch-shifted. Not all of them, only some of them.

The culprit here ended up being silence.

I wish this was a joke.

The part of my script that was responsible for converting the provided title images into short video clips to add before the main talk content needed to create a few seconds of silent audio to play while the title image showed. This was to ensure the rest of the audio started playing as soon as the title slide was done, and not before.

(Now is your chance to check “multiple types of silence” off your “why is the video broken” bingo card…)

These digital formats that represent sound have to make tens of thousands of measurements per second so they can approximate that same sound later. While the end result may sound the same, some audio files use 48,000 samples per second, whereas others use 44,100. This may seem like a difference of only fractions of a second, but it can affect how precisely sounds get stored, specifically higher-frequency sounds.

Because this silent audio track was configured at this faster rate, it caused the whole video file to treat all of the sound as if it was recorded at this faster rate, even though the audio from the event was recorded at the lower speed of 44,100 samples per second. This difference caused the audio to play back about 8% faster than it was recorded, leading to two separate audio issues in the recordings:

1. A noticeable “pop” or moment of silence every few moments when the faster-playing audio ran out of data and had to wait until the next audio chunk.
2. Audio incorporating higher-pitched tones would seem more noticeably pitch-shifted and warped compared to audio with only lower tones. This was because higher frequencies are more sensitive to this difference in playback speed than lower tones

4. Human Problems and Miscellany

Another technical problem: YouTube forces scheduled videos to be private. It is not possible to schedule a video to go from unlisted to public on a particular date. The videos MUST start as private. This created some friction since I was using YouTube Playlists to soft-publish the unlisted videos before they were fully published.

The rest of the issues are things I would lump together as “human problems” on my part. These included things like:

• Forgetting, or incorrectly performing, some of the steps in process that were not yet handled by the automation (such as removing non-talk “break” sessions from the schedule prior to processing)
• Not manually checking every minute of every video. This would have been really time consuming given how many hours of video there were, so I just… didn’t. This decision led to a snowball effect of additional issues, such as the YouTube comments identifying quality issues in some of the early videos. Since the URLs had already been manually added to the schedule, pulling down and re-uploading the videos again would be even more manual work that would slow down the releases of the remaining videos.

Shout Outs

I would like to shout out everyone who helped make these uploads happen, including:

• Justin, Aoife, Natalie, Dorka, and everyone else who helped run Flock 2024
• The media team from On Site A/V, who provided and managed the capture and presentation hardware and were great to work with (especially Greg)
• YouTube commenter @gabrielrmattoso for contributing post timestamps on many of the talk videos (these were an awesome sanity-check to make sure the automations were working and helped shortcut the process by a lot!)
• Everyone else who left YouTube comments to point out errors with the videos. Your feedback helped me catch the issues sooner!

So what could be better for next time?

Ultimately, I think the process can be improved next time by:

1. Potentially having some better tooling to systematically check/review large batches of videos, but in a way that can spread it across a whole review team (maybe with some kind of web interface)
2. Clearer guidance for speakers on how they should input their name into PreTalx since the scripts currently just use that as-is for the thumbnails.
3. Reducing the tedium with (potentially) some more automations for things like uploading to YouTube, or attaching the YouTube URLs to the PreTalx Schedule.

There I was, moving out of my summer housing. I had put my last load of laundry in the machine and noticed my account balance was down to $1.

I knew the laundry machines in my particular housing complex would sometimes charge $0.25 extra when I enabled certain settings, such as when I changed the washer from a “light” load to a “normal” one. I also knew I would be back again in 30 minutes to move my clothes to the dryer. I checked the dryer to see if I could run a load and use up this last dollar. Maybe by setting it to Low Heat? nope. Delicates? Nope, it seemes like the price of a dry cycle was set at $2 - fair enough.

On my way back upstairs, I thumb through the LaundryConnectPay app that I have been using for laundry for most of the summer. I have reloaded my laundry balance several times at this point and overall had a fairly positive experience with this app so far. Sure it had its quirks, but this app has a box to input a custom amount, so it should be easy.

The fact that you’re now reading a blog post about me paying for my laundry means it was not quite so easy.

When I did the intuitive thing and typed in $1 into the “custom amount” box, I was told the minimum reload was $10. Fair enough. Many companies do in fact set minimums to ensure that the credit card transaction fees (typically $0.30 + 3% per transaction) don’t unreasonably eat into the actual transaction value. Granted $10 seems a little high compared to other minimums that I’ve seen, but what do I know about the world of laundry?

At this point I figured if there was a $10 minimum they would at least have some kind of refund policy to pay back the money in the event of account closure. However, I was somewhat surprised when I noticed that nowhere in their terms of service were any of the words “remove”, “delete”, “close”, or “cancel” mentioned. The only reference to account closure was in the section that stated that Automatic Laundry reserves the right to remove my access to their service at any time. That said I do have to give them credit for having incredibly short and easy to read terms.

Actually, its worth noting too that these terms only apply to “this website” (presumably referring to the website the terms are hosted on - automaticlaundry.com). In fact, on further investigation, it appears that the account related functions of the app are done largely through an embedded web page run by kiosoft and governed by their terms (LaundryConnectPay could be a rebadged version of their KioSoft CleanPay service - not sure). A few interesting things to note about this set of terms as it relates to my desire for a refund of any leftover balance from my account:

1. Section 6.4, seems to essentially be KioSoft dodging responsibility for providing refunds and passing it back to the “laundry facility operator” (so does that mean my now-former landlord?). Despite its length, its notably lacking in specificity. The language makes me think they had “refunds for paid-for laundry cycles” in mind when they wrote it, but did not mention refunds on account closure.
2. Section 8.3, which reads “We will not be responsible for any support or maintenance for the App” (this will become relevant later).
3. The header for section 14 “GOVERNING LAW AND AGREEMENT TO ARBITRATE ON INDIVIDUAL BASIS” isnt so much important as it is funny, as they seem to have learned absolutely nothing from the mistakes of doordash

The discovery of a new Dark Pattern

So I had a simple question about refunds and ended up discovering that both the brand whose logo is on the app AND the maker of the technology behind the app both consider refunds in the event of account closure to be not their problem in some way (either by explicitly saying it, or by conveniently leaving it out of their terms).

It was only upon perusing through my account settings in the LaundryConnectPay app that I encountered the big red “Close Account” section that made everything clear.

The moment I noticed the checkbox next to the statement “I agree that my account balance will be wiped as I close this account” I realized there was another explaination for the $10 minimums, the buck-passing, the lack of detail in the terms, and the sheer number of steps it took to even learn all this in the first place. Maybe they don’t want people to have a zero balance when they close their account.

Dark Patterns, also known as “deceptive design patterns” are user interfaces or design choices that have been carefully crafted to trick people into doing things. These patterns “are relying on you to either not notice what’s going on or to be too busy to do anything about it” (Gizmodo). Curiously, deceptive.design, a website listing different types of dark patterns, didnt seem to have any entries about this nonzero balance pattern. However, given that I have seen this kind of behavior before (notably while trying to use up a gift card balance at Dunkin’ Donuts), I think it deserves to be included in the list of dark patterns.

By using these manipulative tricks to skew the system such that there is a bias towards people closing their accounts with a nonzero balance, its possible to increase the amount of money that either expires, gets forfeit, or just sits unused in an account somewhere. Whether through simply being given money, or by investing it (did you know starbucks makes more money acting in bank-like ways than from selling food?) its pretty obvious that the reason behind the use of this pattern is the same as nearly every other dark pattern: profit.

How can affected laundry-doers fix it?

But when a long train of abuses and manipulations, pursuing invariably the same Object evinces a design to reduce them under absolute Capitalism, it is their right, it is their duty, to throw off such Systems, and to provide new Alternatives for their future technology.

So, you use the LaundryConnectPay app, have a load of laundry to do, but don’t want to deposit a full $10 only to not use it all? Well have I got a workaround for you (don’t worry its easy and doesn’t appear to violate any of the terms of service - I may not be a lawyer, but I checked).

It all started from the add funds page….

This is where I noticed something odd about the page. There seemed to be a weird looking zoom icon in the bottom right corner. This suggested to me that this page of the app was in fact a webpage embedded into the app. Luckily enough, I didn’t have to look much farther than the LaundryConnectPay website in order to find the link to the web verson of this portal, which was located at https://alslaundryportal.com/tenant.

It was in poking around that page that I noticed the buttons for the pre-filled payment options were hyperlinks that all looked like this: https://alslaundryportal.com:5009/tenant/refill_account_confirmation/<amount>

Is it really that simple? After testing it turned out that the answer was indeed yes.

So basically the short answer to “How can I add less than the $10 minimum to my LaundryConnectPay balance?” is to be logged into the laundry portal on a computer, change the number at the end of the URL above to the amount you want to deposit (must be at least 1 based on my testing, but it does seem to accept fractions of a dollar), visit the link, and then click the confirmation button to charge your saved payment method and top up your account.

If it helps, here are some shortcuts for some amounts I think might be common:

• Reload $1
• Reload $1.25
• Reload $1.50
• Reload $1.75
• Reload $2
• Reload $2.25
• Reload $4
• Reload $5

And the best part is, you ultimately pay what you owe for laundry.

To the companies perpetuating these dark patterns

Realistically I’m just an individual and am not really in any position to tell a corporation what they should or shouldn’t do, but the way I see it, there are three paths forward (roughly ordered from pro-consumer to anti-consumer):

Path 1: The Ethical Path Operate in good faith and work to find a resolution that makes everyone happy. I propose some combination of:

• lowering the minimum reload value offered in the UI
• providing people with a proper refund on closing their account
• generally helping people feel like they haven’t just been ripped off (such as when they are told they have to pay $10 when all they want to do is run a $2 laundry cycle)

Basically in general, stop biasing the system such that it encourages people to maintain a nonzero balance.Also stop making it even more difficult for people who want to zero out their balance at the end of their tenancy. While it may not affect most people, everyone’s brain works differently, so I wouldnt be surprised if some people were personally bothered just by the knowledge that some unused amount was sitting in their account and couldn’t be used.

If the loss of money or profits makes this hard to implement, there are still options:

• people could at least be given the option to deposit smaller values in return for having to pay for some or all of the CC fees associated with depositing these smaller increments
• people could be given a refund by default and, upon account closure, be given the choice to give this up, donate it to their laundry operator, or donate it to a charity (maybe it’s tax-deductible)

Path 2: The Doing Nothing Path While it’s not great to be publicly known as a perpetrator of Dark Patterns, doing nothing is probably the most likely path (especially considering the “We will not be responsible for any support or maintenance for the App” from the terms of service earlier). If anyone from any of the involved companies even sees this and decides to raise it internally, its going to be quite a fight to convince anyone with the power make a change to do so solely on principle.

Path 3: The Striesand Path Of course, there’s also the chance that there will be an attempt to shut down this workaround (you know the classic conceal, don’t feel, don’t let them know - Except now they know because there’s a blog post about it 😜).

While its hard to predict what happens in this scenario, I imagine that the niche-ness of this usecase wont actually be enough to create a full-blown public version of the Striesand effect.

That said, never underestimate a group of nerds who care very much about something and are willing to put in way more time than its worth to fix the issue (there are people out there who have committed real life crimes over Minecraft).

I suspect any action that impacts the ability to use this workaround (such as by limiting the links so that they only work for the specific pre-set reload values they were meant for) without fixing the underlying dark pattern would only serve to potentially annoy a group of people who cared enough to find this workaround in the first place. At worst this could potentially start a never ending cat and mouse game that could turn into full-blown Striesand effect.

In Summary

“Isnt finding a workaround and writing up a blog post a lot of effort to go to over $10? havent you spent way more than $10 in the time it took you to do this?” - everyone

Yes, and thats kind of the point. If nobody ever takes a principled stance on anything, then companies like those mentioned here can continue to exploit and profit from the gap that exists between what is “the right thing to do” and what people are willing to take action over. It’s the same underlying concept behind enshittification - perpetual twiddling of the algorithm until you discover just how many ads people will tolerate before they are willing to leave alltogether. Laws that aren’t enforced, or aren’t enforced with big enough fines tend to get broken, ignored, or treated like a cost of doing business. Principles that aren’t enforced strongly enough will likely suffer the same fate.

First they ignore you, then they laugh at you, then they fight you, then you win - Amalgamated Clothing Workers of America, 1918

In all honesty I’m still not entirely sure what compelled me to write this. It certainly ended up being a great opportunity to talk about how subtle interactions in the systems we use every day can make our technology feel unfriendly, hostile, manipulative, abusive, or just disrespectful of us as people.

I also feel like this is worth writing about not only because it serves as documentation that can help people who are stuck using this app in order to do basic life tasks make their technology feel slightly less abusive to them.

Even beyond that, it’s also an excellent example of the kind of impact I want to have on the world. For a while I have known that I want to use my skills and experience to make peoples lives better, but I have never really been sure of how to say that without just sounding like I’m reusing a cliche. While it may take me a while longer to fully figure out all the different ways that I’m interested in making a difference, this is at least one small example that helps me get closer to that end.

How memory is measured

Broadly speaking, memory pressure measures how much system performace is being impacted due to memory not being available when it is needed. This can be measured in a number of ways, such as how long the system spends waiting for memory to become available for a program or whether the system has to fall back to using slower techniques like compression or slower methods of storage (like your system disk) to assign memory.

In contrast, the traditional measurements of available memory in Unix-like systems often aren’t the most intuitive to use as a performance metric for the average person. On a system with 16 GB of available memory (and depending on what you are doing), the difference in system performance between having 4, 6, 8, or even 12 GB in use is likely not going to be as noticeable as the difference between 14 and 15, or 15 and 15.5. Essentially the closer you get to using all available memory, the more the system struggles to fulfill each new request for memory.

A pressure-based model can help provide a better indication that the system is struggling long before it becomes noticeable in the form of performance loss. For example, if there was a metric that measured how many nanoseconds or processor clock cycles a system spends waiting on memory allocation, problems would be measurable far sooner than they would be noticeable to the end user. If the metrics were able to indicate that the system is spending 1-2% of its time waiting for memory and that this has increased over the past few minutes, the future degradation of system performance can be reasonably well predicted and the system could take steps to avoid this scenario more proactively.

Pressure Stall Information

Since version 4.20 of the Linux kernel, which was released in December 2018, pressure metrics for memory, as well as other system resources like CPU and IO have been available on Linux-based systems through special files located at /proc/pressure/.

Ever since learning that this information was available around 2020 or so, I began figuring out how to add this information to the system monitoring tool that was installed on my system at the time (which was callled ksysguard). The solution I ended up with involved creating a DIY perl script to read the data and display it as a graph.

Upgrades people upgrades

Not long after getting this somewhat hacky solution working, I updated my computer. This introduced a different, more modern system monitoring tool that also happened to conveniently not work at all with my newly-built memory pressure monitoring setup. Since it would be nice to to be able to view system pressure information inside the new system monitor application, rather than having to resort to using two different apps, I started looking into ways that I could get this information added to the new system monitor.

I initially searched for a way to do this as a plugin that users could download via something like the KDE add-ons store, however I couldn’t find documentation or examples for how to create one of these plugins for new sensor data sources (the only options seemed to be either to create new data visuals or custom graph layouts, not new sensor data sources).

My search for how to add new sensors also led me to lm-sensors, which seemed to be for more traditional hardware-backed sensors (such as for system temperature, clock speed, .etc). What I needed was more of a “virtual” sensor since system pressure really only means anything if software is running on the machine (unlike temperature, for example, which exists as a property of the hardware regardless of if the system is even turned on or not).

The quest for pretty graphs continues

Eventually, all this searching around and asking in matrix chat rooms led me to ksystemstats, which appeared to be the repository providing the core sensor data behind the updated system monitor application. This repository also seemed to be composed of several plugins to group the sensor data. This made it relatively straightforward to study and copy from existing plugins (such as the osinfo plugin, which seemed close enough to what I was going for).

Not long after I started making my changes to ksystemstats I updated the project to target the Plasma 6 core libraries in order to either fix some bugs or to keep up with the rest of the KDE developerverse as things switched over to a new version of the core libraries. To be honest, the majority of this project happened over such a long time that I barely remember much more than the high level overview anyway. The few notes I did take were largely focused on how I set up my development environment and how I worked around some issues I kept running into with that setup. I hope to convert this into a more proper list of steps and post it as a separate technical post for any new KDE contributors who want more technical detail and also had trouble finding out where to get started when developing for KDE.

The end result

Despite the long timeline, I’m happy to announce that as of the publishing of this post (actually as of a while ago - I kinda procrastinated a little bit), my system pressure sensor data source has now been merged (and mentioned in another developer’s blog post).

While I tried to write my new plugin code as cleanly and maintainably as I could (since I know the KDE developers would ultimately be in the better position to maintain this) a merge request submitted soon after mine helped point me to a (thankfully small) area where my code needed just a little more work).

As much as I tried to endure things would go smoothly the first time, I’m still excited to see my changes make their way through the testing process, destined to be shipped in the upcoming 6.2 release of KDE Plasma.

Takeaways

Being able to finally sit down, think back, and publicly document this project has given me a valuable reference point from which to measure some of my current experiences.

As my first KDE contribution, I think this project gave me a great slice of new perspective into what the experience is like contributing to a system as large as KDE. If I hadn’t been self-motivated by my desire to add pressure statistics to my system, there would likely have been many points at which I would otherwise have given up. Thoughout this project I got to experience learning (and/or re-learning) C++, setting up (and updating, and un-breaking) a larger system-scale development environment than I ever have before, navigating incorrect or outdated documentation, joining chat rooms and politely asking for directions until I found my path, as well as one of the longest review timelines I’ve had for a contribution.

While most of these things sound quite negative and can be painted as “problems”, my more recent experiences joining and interacting with the Fedora community suggest that many of these things aren’t unique to KDE and are more likely to be just facts of life for those who work with large technical systems.

If you want to go fast, go alone. If you want to go far, go together

Thanks to everyone who helped provide significant feedback to help get this change merged: David Redondo, Arjen Hiemstra, Mike Noe, and anyone else who helped either throughout the review process or to help point me in the right direction on matrix. I wouldn’t have been able to navigate my way through this change without the corrections you all provided me when I got off track.

Whether this is from my more recent experiences with similar projects or from reflecting on this contribution (and at the risk of oversimplifying my thoughts for the sake of a metaphor) I think the one message from this project that I wish to pass on to anyone who needs it is this: Making a difference in the world of Open Source is primarily about people. While a license is often seen as the singular defining factor of open source, I think it’s better described as the ribcage, protecting and creating the space for true heart of open source - the community and the people who are part of it.

How did this start?

For the past several years I’ve been interested in learning more about how open source projects develop from a small “hello world” or personal side project into large, well-known tools with thriving communities.

One of the greatest strengths of open source is sharing. An excellent example of this is the technologies, protocols, and software powering the internet (TCP, HTTP, BGP, Apache, etc). All of this infrastructure is built with largely open standards and open code. This takes full advantage of open source’s greatest strength. When everyone can see the same code, everyone can be on the same page for subsequent discussions of how to improve the code. Having open code then provides a foundation of transparency that empowers anyone, from any background, to review and raise issues about the code (thus improving security, accessibility, and many other areas). Such transparency also brings benefits even for those who aren’t actively contributing, such as making it easier to build compatibility into other projects, speeding up adoption and enabling project growth as was the case for the internet.

Over the years I’ve seen projects that even have formed self-sustainable business ventures around their open source projects, even despite the increased difficulty of doing so in the open source world. These types of projects, such as SnipeIT, are smaller than the typical examples of financially sustainable open source projects (such as Red Hat, Python, Drupal etc.) and I think they serve as a useful point of comparison, along with some of my other projects (such as ClassClock), to help fill in the path for those with dreams of creating the next big open source company, bringing the benefits of open source to a new industry, or simply adopting more open-source ideas in day to day life.

Some background for non-rowers

Concept2 is a company that manufactures rowing equipment and is primarily known by rowers for their indoor rowing machines (also known as “ergs”). All new Concept2 indoor rowing machines sold today have bluetooth support built into the screen (referred to as the “performance monitor” by Concept2). This bluetooth support allows rowers to connect a phone and use a variety of apps to save or supplement the existing information displayed by the machine. Concept2 makes most of the technical specifications of this bluetooth interface available to the public so that any developer can add basic support for Concept2 machines into their apps.

Why rowing?

Other than having been a rower since before high school, one of the main reasons I became interested in looking at rowing from an open source lens is that it’s already quite a technologically rich field. Many different apps and companies build on top of Concept2’s largely open specification and, unlike other industries, I believe there is very little that prevents the sport of rowing from becoming a leader in the wider fitness industry.

The reason I chose the sport of rowing was because I noticed that while there are hints of an openness mindset within this industry, very few industry participants are taking advantage of it in the most effective way possible.

The fundamental question driving my curiosity with this research was: How much time could all the apps and services of the rowing industry have saved if they had nurtured the seeds of openness started by Concept2’s standard and worked together to build a single public implementation of this standard for everyone to use?

While there are many ways in which open source can make a lot of sense, even for a for-profit business, I wanted to start by investigating how best to utilize available time and resources for the benefit of the product and/or the customer.

My Process

In order to try and answer this hypothesis, I conducted a brief survey of as many of the 43 apps on the Concept2 list as I could. Right off the bat I wasn’t able to reach out to about half the apps on the list because:

• their product didn’t seem like it actually implemented the Concept2 bluetooth interface (some had their own first party sensors for gathering data or used the camera)
• their website and/or email address was broken (includes attempts to use web contact forms that were broken or otherwise didn’t work)
• I wasn’t able to find a way to contact them

For the developers I was able to reach out to, I sent them a survey link that included questions such as:

• When was support for Concept2 performance monitors first added to your app? (free response)
• At the time, how many people contributed to the technical implementation of this feature? (free response)
• Approximately how long had support for Concept2 performance monitors been planned/on the roadmap before it was implemented and available in the app? (free response)
• Approximately how long did the implementation of support for Concept2 performance monitors take once development started? (free response)

Other questions were also added for meta purposes, such as getting consent to share the gathered data, consent to follow up, etc.

Results

In no particular order, here are some of the observations based on the data.

• At least 6 groups/companies/developer teams responded to my requests to participate in the survey and consented to being named:

  • FIIT

  • Coach Bergenroth, who has created the following apps:

    • rowingSTEM
    • ErgDude
    • ErgMath
    • Remote rowing coach

  • ErgStudio

  • Ergometer.space

  • Swelldone

  • Selfloops

• A large majority of the participants had teams consisting of one person at the time they implemented the Concept2 specification

  The participants seem to be split roughly 50/50 between volunteer-driven projects and apps that appear to be part of a for-profit enterprise (at least based on their websites and educated guessing)

• The answers regarding implementation time were quite varied and in some cases required a lot of assumptions to come to a specific number of person-hours:

  • Paraphrased examples of the raw data: “2 days”, “3-6 months of nights and weekends”, “6 months”, “2 calendar weeks, 40 hour effort”
  • From this, as well as my estimates of how much each participants time was likely to be split with other things (volunteer-driven, part-time staff, full-time staff), I calculated a conservative/low end average for number of hours to implement the Concept2 spec at 137.13 dev-hours per participant (about 3.4 full-time-equivalent/FTE weeks).
  • Similarly, a liberal/high-end estimate was 364.24 dev-hours per participant (about 9.1 FTE weeks).
  • Total developer-hours across all participants surveyed was conservatively about 961.14 dev-hours (24 FTE weeks), and liberally about 2549.71 dev-hours (63.7 FTE weeks)

• The majority of the apps surveyed seem to have been released in the 2019-2021 time period

• Four of the apps surveyed said they were planning to support the Concept2 Bluetooth specification from the beginning. The remaining apps each said they were planning the feature for either one, two, or three months before they began implementing it.

These results, especially regarding time to implement the Concept2 specification, largely seem to track with my own experience as well. Analyzing the commit history of one of my own projects that largely consisted of reading and implementing large chunks of the Concept2 bluetooth interface specification reveals that it took me something close to the ~125-130 developer-hours mark. This seems to lend a little more credibility to the lower, more conservative end of my estimates from the survey.

Analysis

Overall I think this quick research survey was somewhat successful in doing its job of sanity-checking my initial theory. While the time to implement seemed lower than I had assumed based on my experience, it wasn’t so far off what I initially thought to warrant throwing it out.

Due to the limited time I gave myself to perform this research (one semester), these methods are far from perfect or free of bias. However, to me this seems to be a reasonable methodology for an initial sanity-check that open source might be able to boost efficiency within an industry by bringing in some real-world data. While I initially suspected that increased openness could be useful to an already-fairly technological industry such as the sport of rowing, this survey provides the first footholds of data to back up these claims.

As I mentioned ealier, one of the greatest strengths of open source is sharing. Indeed, rowing is also often known as the ultimate team sport. However despite all this it seems as though rowing’s tech industry is still trying to tackle it’s problems with a mindset that “I am on my own in a sea of competitors”, likely inherited from the world of commercial software. I believe that the rowing industry is uniquely positioned to take the open source seeds that it has already planted, and come together as a community to grow a better future for the sport of rowing while also setting an example for other industries to follow. In order to achieve this goal most effectively, however, the industry should adopt a similar mindset to the positive-sum, collective-before-individuals, lifting each other up mindset that both open source developers and elite rowers know very well.

Attempting to use the scale with the openScale app proved unsuccessful and initial research into how the scale worked proved to not have many useful results (maybe they’re all in Chinese given that’s where most sources seem to point).

Disassembly

The most helpful piece of information I found was a series of internal photos of the disassembled device from an FCC filing for FCC ID 2AVEN-CW286. While these photos seem to be from a third-party site, I was also able to find a filing for this same ID using the FCC’s official Equipment Authorization Search and searching for the Grantee Code of 2AVEN.

These photos provided a general idea of how the scale was put together (the feet remain attached to the glass and the plastic housing comes off), which gave me a starting point from which I could attempt to replicate the disassembly.

Here is a diagram of roughly how this scale is put together:

My advice for anyone trying to replicate this would be to first try and get under all four sides and break the adhesive strips holding the two halves together (being careful as there are wires, especially near the LED board). Then, use a pry tool to get under the edge of the plastic and move around to the corners where you can use the pry tool to unclip the clips on the outer corners. Repeating this process for the inside of the ring should allow the plastic ring to come off.

Other than a BK3432 chip controlling the scale and a few pads on the PCB for serial communication, there didn’t seem to be much else of interest. Datasheet-wise, the best I could find was this link from a company that seems to make similar boards based on this same chip.

If I had the proper tools to connect to PCB pads it might be neat to come back and investigate the serial interface of this scale and try to read the firmware and/or write my own (if you do this, I’d love to know).

Software

After reassembling and some poking around the bluetooth interface, I learned that this scale doesn’t seem to provide weight data via traditional bluetooth services and characteristics (like it seems to for battery information and device info), but instead it seems to just advertise the current weight being sensed via the manufacturer information field of the bluetooth advertisement packets.

Here is a diagram of my findings relating to this data field:

This may not be a perfectly accurate diagram, because I only have one scale and didn’t try measuring weights near the scale’s upper limit, however, this interpretation seemed to be adequate for integrating with openScale.

Having never contributed to openScale before, I started by poking around the repository and looking into previously accepted contributions of additional scale support to get a sense of how to add support for a new scale. Thankfully there was a guide on their wiki that helped me gather the bluetooth logs that allowed me to understand how this scale communicated over bluetooth. I was also somewhat lucky to have come across a previous contribution that supported a scale with a very similar advertisement-based operation to this one, meaning I could mostly reuse the same code and tweak it for this specific scale.

I hope this random collection of things I learned while working with this scale helps someone else save a little extra time or headache when working with it.

As part of my university studies I am currently taking a course called Concepts of Computer Systems which explores the more behind-the-scenes aspects of how computers take software instructions and translate that into actions performed by the hardware. As you can probably imagine, this involves some fairly low-level programming in MIPS assembly, which seems to be the most common instruction set used for education.

In this course, when assignments are submitted in assembly, they are run using a custom MIPS simulator called RSIM that was developed by the CS department. In class we have also been using a tool called MARS, which includes a handy debugger for stepping-through the code and creating breakpoints.

A solution looking for a problem

As someone who enjoys many of the movies that marvel makes, I couldnt help but notice that the original developers had made a critical oversight in the naming of the menu options at the top of the program.

After fixing this issue, the menus are now much more enjoyable to use.

Making this change required me to learn how to extract and run the source code that was shipped with the MARS jarfile and was an interesting experience in making surgical changes to code I had never seen before. However, the joke quickly became less funny and left me with the ability to generate new builds of an app and very few ideas for what to do with it. Talking with some classmates revealed the possibly of adding a dark mode to the app, but that still has not happened yet.

Compatibility is never gauranteed

Fast forward a few weeks. The course was going well and we had been tasked with implementing the math portion of a provided MIPS assembly program for computing square roots using Newton’s method. I had created a working solution in MARS, but uploading it to the CS department servers and running it using their RSIM tool caused my square-root calculator to output a very large value in the neighbourhood of 1600-3200 when tasked with square-rooting the number 25.

After a classmate experienced the same issue and reached out to the professor about it, we were told that the issue was due to the way that MARS and RSIM handled the xori instruction. Using the recommended fix solved the issue with my code, but by this point I had become curious about what that inconsistency was in the first place and whether i could fix it with my new MARS fork.

As it turns out, MARS implements many shortcuts (known aspseudo-instructions) that expand out to additional lines of code automatically. One example of a useful shortcut implemented by MARS this way is the instruction addi $t0, 1. Normally the addi instruction takes three arguments: a register to store the resulting output, a register for the initial value, and a 16 bit immediate value. As you might expect, this instruction will add the value stored in the given input register to the immediate value provided and store the result in the output register.

If you wanted to increment a value in-place, a fairly common programming task, you could just use the same register for the input and output values by writing addi $t0, $t0, 1. However, programmers will indeed go to any lengths possible to save typing a few characters, so MARS has added an addi $t0, 1 pseudo instruction allowing you to add values in-place with less typing.

Remember how I said earlier that the immediate value is only be 16 bits? This is because MIPS itself is a 32-bit instruction set, meaning that each register and each instruction is represented by 32 bits. However, because each instruction needs to contain more information than just a single number, there isnt space inside a 32-bit instruction to both tell the computer what to do (i.e. add some numbers) and also provide the 32-bit value that it should add.

Normally, if you wanted to add the hexadecimal value 0xdeadbeef to a register using the operation addi $t0, $t0, 0xdeadbeef, it would likely raise an error or end up only adding 0xbeef because the immediate value can only hold 16 bits. However, using pseudo-instructions, MARS creates a shortcut that inserts additional instructions to handle 32-bit values, meaning the addi $t0, $t0, 0xdeadbeef instruction from earlier would work as you would expect.

So how does RSIM handle 32 bit immediate values? RSIM’s implementation of MIPS assembly takes the approach that a 32-bit immediate value is not legal, meaning that if a 32-bit value is provided, such as in the 0xdeadbeef example, it is treated as an error. However, if the value happens to be something like -1 which can be represented in both 16 and 32 bits, RSIM will only use the lower 16 bits, resulting in a value of 0x0000FFFF instead of 0xFFFFFFFF.

This was the problem that was causing my code to break in RSIM but run perfectly fine in MARS.

A new teaching tool

Since I now had the ability to make changes to MARS and I now knew exactly what the problem was, I dove into the MARS code to see if I could fix the problem.

Being brand new to the codebase initially led me down a few false paths, but eventually I discovered that there was a PseudoOps.txt file within the MARS codebase. I had initially assumed that this file was some kind of documentation until I discovered that I was able to comment out entire pseudo operatons and create brand new ones just by changing lines in that text file.

Talking with my professor revealed that changing this single text file could also give MARS a wide range of additional classroom capabilities. Some of these additional uses include:

• overriding the default pseudo operations so that MARS operates in the same way as RSIM, eliminating shortcuts that are not allowed to be used for assignments
• progressively expanding the set of pseudo operations as students learn them by simply distrubuting this pseudoops file
• allowing students to write their own pseudo operations to create their own flavors of MIPS assembly

Allowing different versions of this file to be passed in by the user, rather than just being a hardcoded path to an embedded resource in the .jar file, would also allow this file to be changed without needing to rebuild MARS each time.

The final product

After a couple days spent implementing this new feature in the MARS source code I had a working version that adds a new Settings > Pseudo Operations… menu, allowing end users to select the path to a modified version of the pseudoOps.txt file.

The jarfile for this version has been released to github as an unofficial MARS version 4.5.2

While using the MARS debugger to set breakpoints and step through code makes learning assembly so much easier for students, I hope that this additional flexibility for custom pseudo operations helps to give teachers more control ofer the available shortcuts when using MARS in the classroom.

For the past few months or so, I have been involved with a few COVID relief projects after some friends and I got together to create vacfind.org (Note as of January 2022 the domain is no longer controlled by us and should be treated as NSFW) to try and help out wherever we could. Even as vaccine supply exceeds demand and the general chaos seems to be winding down, I couldn’t resist the opportunity to make some easy pull requests to ingest a bunch of data to feed into the comprehensive nationwide map of vaccination sites at https://vaccinatethestates.com.

After some brief conversations with the VaccinateCA team and a few small pull requests to get a feel for their workflow and how the data ingest pipeline worked, I was already working on contributing an entire data source from GISCorps with nearly 30,000 vaccination sites in it.

While working on the python script to convert the data to the format that the ingest system wanted, I discovered a field that listed the operating hours of the vaccination site. This field contained data such as:

Monday - Friday 8:00 am - 2:00 pm

Saturdays 9:00 am - 12:00 pm

Mon- Fri 9am-4pm

7am-4pm

8:30 am - 3:15 pm

M-F 8 am to 4:30 pm

8 am to 8 pm daily

Every Day 8am to 8pm

8:00 a.m. - 4:30 p.m. Monday through Friday

null

by appointment only

9am-5pm, Urgent hours available

Because of how unstructured this data is, it seems as though this field was meant to be directly displayed to users, rather than processed by a machine.

Despite that I went looking for a library that could parse this. A quick Github search only seemed to turn up parsers that worked with the OpenStreetMap opening_hours format, which would likely not work here.

Be the change

With no existing solution easily available, I figured it would be useful to the broader Python community if I made my own. Starting with some of the more straightforward strings from the GISCorps data, I began building up sets of expressions for the various time formats and days of the week using the pyparsing library and whatever I could remember about context-free grammars from my Computer Science Theory course.

For a library like this that simply takes in strings and other primitive data types and spits out some JSON, it was also incredibly easy to write unit tests as I went. While normally I’d find writing tests to be a slog, these tests were quite simple and pleasant. I was able to take an almost-test-driven approach by adding any new cases that I came up with to the unit tests first, then using the unit tests to run the code and see if it worked.

Since releasing an initial “MVP” version to PyPi on May 3rd, it seems to have gotten about 211 downloads so far according to PePy. While it is super awesome that people are (likely) downloading and using this library, I can’t help but notice the similarity with my Jekyll encrypted web payments library on RubyGems whose downloads also seemed to shoot up to about 200 in the first few days, before completely stagnating.

Given the timing of the downloads on both these libraries, I suspect the cause of this is just a bunch of bots constantly watching for new packages and mirroring them to other repositories or who-knows-what. While bots are the most likely explanation at this point, being able to say that my code is used by real developers is a much happier outlook, so at this point, I’ll split the difference and say I pretty much have no idea what’s going on with the downloads on these libraries.

Overall, I’m very proud of how well this library is already able to parse many new test cases that I come up with. I’m looking forward to continuing to work on it and expand it to handle more real-world formats for operating hours soon.