👋 Hi, my name is Max Zsol.

I'm a computer engineer and writer of sci-fi, some times with the help of AI.

I also blog about writing, mindfulness, engineering leadership, mechanical keyboards, and a long etcetera.


mindfulness
January 18, 2023

Be More Regular Creating A Wholistic Life

Be More Regular Creating A Wholistic Life

Here are my key habits for a well-rounded life:

January 18, 2023 · #mindfulness

mindfulness
January 17, 2023

A state of Flow

The book Flow: The Psychology of Optimal Experience by Mihaly Csikszentmihalyi is one I keep coming back to for the ideas on it, and has been one of the most influential of last year for me.

Here are some quotes and takeaways from the book:

“It’s exhilarating to come closer and closer to self-discipline.”

― Mihaly Csikszentmihalyi, Flow: The Psychology of Optimal Experience

“The best moments in our lives, are not the passive, receptive, relaxing times—although such experiences can also be enjoyable, if we have worked hard to attain them. The best moments usually occur when a person’s body or mind is stretched to its limits in a voluntary effort to accomplish something difficult and worthwhile.”

― Mihaly Csikszentmihalyi, Flow: The Psychology of Optimal Experience

“The mark of a person who is in control of consciousness is the ability to focus attention at will, to be oblivious to distractions, to concentrate for as long as it takes to achieve a goal, and not longer. And the person who can do this usually enjoys the normal course of everyday life.”

― Mihaly Csikszentmihalyi, Flow: The Psychology of Optimal Experience

January 17, 2023 · #mindfulness

mindfulness
January 16, 2023

On too much focus

Too much focus

There is such a thing as too much focus.

I do experience it every now and then. When I obsess over a piece of code, or I go down the rabbit hole of doing my taxes.

In those moments I find myself as if awakening from a daze realizing I’ve spent the last few hours deeply busy with the task at hand.

This is the state of flow, which is one of the most enjoyable states to people.

“The best moments usually occur when a person’s body or mind is stretched to its limits in a voluntary effort to accomplish something difficult and worthwhile.”

― Mihaly Csikszentmihalyi, Flow

As much as I enjoy those moments of flow, I am learning that there is such as thing as too much flow and too much focus.

Mindfulness is an effective path here. To find my balance I pause and take a deep breath.

We seek the flow, but we must find balance as well. Letting go is part of being on the flow.

“Whether we are happy depends on inner harmony, not on the controls we are able to exert over the great forces of the universe.”

― Mihaly Csikszentmihalyi, Flow

January 16, 2023 · #mindfulness

writing
January 15, 2023

Writing Hooks

Attracting attention with your writing is a vital part of capturing your reader’s interest and keeping them engaged. One effective way to do this is by using multiple hooks throughout your text.

Hooks are parts of the text that serve as entry points for the reader. They are the first thing that catches their eye and draws them into the piece.

Highlighting content

Some examples of hooks include headlines and sub-headlines, bold text, lists, and paragraphs. These elements break the rhythm and can be used to create a sense of intrigue, curiosity, or importance that encourages the reader to keep reading.

Section dividers

In addition to these entry points, there are also things that can break up the reading experience and help to hold the reader’s attention.

Overall, incorporating multiple hooks into your writing is an effective way to capture and hold onto the attention of your readers. By using a variety of entry points and breaking up the reading experience, you can create a more engaging and enjoyable experience for your readers.

—MZ+đŸ€–

January 15, 2023 · #writing

January 14, 2023

The core tenets of rule-making and rule-living

  1. Rules are restrictions on behaviors.
  2. Restrictions beget creativity.
  3. Rules beget creativity.

rule-making and rule-living

Living by rules may seem restrictive, but in reality it can be incredibly liberating and inspiring. Having a set of guidelines to follow can free you from decision fatigue and help you focus on what truly matters. It allows you to channel your energy and creativity into making meaningful choices and taking purposeful actions.

As Austin Kleon says, “Creativity is subtraction”, not addition. Rules give us boundaries within which to work, providing a framework for our ideas and actions. They also give us a sense of structure and purpose, helping us to stay on track and achieve our goals. When we live by rules, we are able to tune out the noise and distractions of the world, and focus on what is truly important to us.

Embrace the rules, and see how they can help you live a more meaningful and fulfilling life.

—MZ+đŸ€–

January 14, 2023 · #miscellaneous

writing
January 13, 2023

Recap of 100 days of daily blogging

Recap of 100 days of daily blogging

Back in October of last year, I set to write and publish on this blog every day. This week I crossed the milestone of 100 days of consecutive posts.

I have been intrigued by the activity of daily creation for a long time. I am fascinated by people who consistently create and publish. Austin Kleon talked about the value of regular practice. Focusing on quantity can help free us from the pressure of perfectionism and might even deliver better results in the long run than focusing on quality.

When I started writing daily I was trying to dry the well. This is a similar idea to Julian Shapiro’s Creativity Faucet:

Visualize your creativity as a backed-up pipe of water. The first mile is packed with wastewater. This wastewater must be emptied before the clear water arrives

Because your pipe has only one faucet, there’s no shortcut to achieving clarity other than first emptying the wastewater

—Julian Shapiro

We have to get through all the bad ideas before we get to the strong ones. To do that we have to turn off our inner critic and create freely and really let it all out.

Seth Godin said it best:

The goal is to get bad ideas. Because once you have enough bad ideas, then some good ones have to show up

—Seth Godin

There are many benefits of writing (ideation, mental health, mindfulness, etc), but here’s what I have learned from writing 100 posts in 100 consecutive days:

Looking back at the last 10 years of writing I haven’t always been this consistent, but this is not the first time I start a project of daily practice. I wrote 101 science-fiction flash-fiction stories in 101 consecutive days, and I am currently on my 262 day of fiction writing (for a novel that might or might not ever see the light of day).

If you need inspiration here are some posts I wrote about other creators who believed in the power of the daily practice:

You know, in order to do something, you need to organize your time. It is very easy to do — you organize your time. You say, “One hour a day you will write. From this hour to this hour, I will write that. And even if I don’t have idea, one hour I write. Even a line. Even three words. But I write. Every day I write.” You organize your time and then you do whatever you want. You take your time like your friend and you don’t lose your friend. Because your time is your life and then you organize your life. I do that, everyday I do that.

—Alejandro Jodorowsky

January 13, 2023 · #writing

January 12, 2023

Machine Art

Machine Art

When it comes to digital art, the terms ‘generative art’ and ‘algorithmic art’ are often used interchangeably. But, in reality, these two forms of digital art have distinct characteristics and different origins. Understanding the difference between these two forms of art is crucial to appreciate and evaluate them properly.

Art doesn’t have to be just about the final product. It can also be about the process of creation. And that’s exactly what generative and algorithmic art are all about.

Generative Art

Generative art is an art form that uses algorithms and computer programs to create artworks that are unique and unpredictable. The artist creates a set of rules or an algorithm that the computer uses to create a work of art, but the final output is not determined by the artist. The focus of generative art is on the process of creation and the relationship between the artist, the algorithm, and the final artwork. In generative art, the algorithm is an active participant in the creation of the artwork, rather than just a tool for the artist to use.

“Generative art refers to any art practice where the artist creates a process, such as a set of natural language rules, a computer program, a machine, or other procedural invention, which is then set into motion with some degree of autonomy contributing to or resulting in a completed work of art.”

—Philip Galanter

A great example of generative art is the work of Joshua Davis, an artist who uses algorithms to create mesmerizing patterns and designs. His work often features organic, flowing shapes that seem to be in a constant state of motion. The beauty of Davis’s work is not just in the final outcome, but also in the process of creation, as the algorithm generates unique and unpredictable patterns every time it is run.

Machine Art

Algorithmic Art

On the other hand, algorithmic art is a form of digital art that uses algorithms as a tool for creating art, rather than as the primary focus. The artist uses algorithms to create artworks that are highly precise and predictable, often with a specific outcome in mind. In algorithmic art, the algorithm is a means to an end, rather than an end in itself. The focus of algorithmic art is on the final outcome, and the artist uses the algorithm as a tool to achieve their desired result.

I write computer algorithms, i.e. rules that calculate and then generate a work that could not be realized in any other way. It is not necessarily the system or the logic I want to present in my work, but the visual invention that results from it. My artistic goal is reached when a finished work can visually dissociate itself from its logical content and convincingly stand as an independent abstract entity

—Manfred Mohr in Art of the Digital Age

A great example of algorithmic art is the work of Golan Levin, an artist who uses algorithms to create interactive installations and digital sculptures. His work often features intricate patterns and shapes that are highly precise and mathematically generated. The focus of Levin’s work is on the final outcome, and the algorithm is simply a tool that he uses to achieve his desired result.

Machine Art

The connection with Process Art

Generative art and algorithmic art have a strong connection to “process art,” a movement that emerged in the 1960s, characterized by the use of non-traditional materials, and the emphasis on the act of creating rather than the final outcome.

In this way, generative art and algorithmic art can be seen as a natural extension of the process art movement, as they both focus on the process of creating art through the use of algorithms and computer programs. In Generative art the algorithm is an active participant in the artwork creation and in algorithmic art, the algorithm is a means to an end, rather than an end in itself.

In closing

It is indeed a surprising and fortunate fact that nature can be expressed by relatively low-order mathematical functions

—Rudolf Carnap

In conclusion, generative art emphasizes the process of creation and the unpredictability of the final outcome, while algorithmic art emphasizes the precision and predictability of the final outcome.

Understanding the difference between these two forms of art is essential to appreciate and evaluate them properly.

January 12, 2023 · #miscellaneous

January 11, 2023

32,872 days

32,872 days

Life is fleeting.

Time is our most precious resource. It is the one thing we can never get back once it’s gone.

Consider this: if you are lucky to live to be 90 years old1, you’ll have only 32,872 days to spend on this earth.

But the real question is not how many days we’re allotted, it’s how many we have left. If you’re in your early 20s, you may have 22,500 days remaining. And if you’re in your early 40s, that number might be closer to 15,000.

As you think about those numbers, ask yourself: How am I spending my days? Are you living the life you want to live, or is it time to start designing a life that truly aligns with your values and passions?

In the end, time is our most valuable commodity. Life is short, and it’s up to us to design it in a way that makes us truly happy and fulfilled.

Carpe diem, my friends. Seize the day and make the most of every single moment. Because, before you know it, the clock will run out.


  1. The world average age of death is 72 years (81 years in the European Union, 77 years within the US).↩

January 11, 2023 · #miscellaneous

January 10, 2023

3 Rules for living (a life of rules)

Rules for living (a life of rules)

Many of us have likely heard the phrase “rules are meant to be broken.” But when it comes to living a meaningful and productive life, rules can actually be quite helpful. In fact, having a set of rules to live by can provide structure and direction for our actions, helping us to make better decisions and achieve our goals.

So, here are in detail my top 3 rules for living a life of rules:

Rule #1: Write down your rules

Rule number one for living a designed life is to write down your rules. This might seem like a simple step, but it’s crucial for creating a clear understanding of what you want to accomplish. When you write your rules down, you’re putting them in a tangible form that you can refer back to, and they become more real to you.

Rule #2: Follow your rules

This is where the rubber meets the road, and where many people tend to fall short. Having rules is one thing, but following through with them is another. It takes discipline and a sense of purpose to stick to your rules, but the rewards are well worth it. By following your rules, you’ll be building momentum and making progress towards your goals.

Rule #3: If a rule doesn’t work, rewrite it

You should be always looking for ways to improve your rules. Sometimes, you might find that a rule that you’ve set for yourself is no longer working for you. In this case, it’s important to not ignore it, but to rewrite it. By being open to changing your rules, you’ll be more adaptable and more likely to find what works best for you.

To sum up, the rules for living a life of rules and a designed life is to write them down, follow them, and be open for changes. Remember, rules are not a set of restrictions to limit your life, rather they are a roadmap for the direction of your life. They are there to help you become the best version of yourself and achieve your full potential.

January 10, 2023 · #miscellaneous

writing
January 9, 2023

The 4-Notebook Method for Life Planning and Organization

The 4-Notebook Method for Life Planning and Organization

As someone who values organization, I’ve found that using four notebooks helps me keep my writing, to-dos, and miscellaneous notes in order. These notebooks include:

  1. The Journal: A place for reflective writing and long-term goal planning.
  2. The Daily Planner: A spot for tracking daily tasks and appointments.
  3. The Organizer: A notebook for organizing projects and ideas.
  4. The Pocket EDC: A small notebook that I can always have on hand for quick notes and reminders.

Each notebook serves a specific purpose in helping me stay organized and productive. Here’s a closer look at how each one works:

Notebook 1 - The Journal

In this notebook, I keep track of my daily reflections and journaling entries. It serves as a place for me to do free writing and brain dumping, as well as to keep track of lists and other information. I write the date at the top of each page before getting started.

With 400 pages, this notebook, which I affectionately call the Hulk, has the potential to last for years.

Notebook 2 - The Daily Planner

Small but mighty. A daily planner has a calendar and one page per day. This is the analog replacement for both my calendar and todo app. All the tasks I have to do get entered in the planner.

The advantage of using a notebook instead of an app is better focus. It is easy to find and write what you need and there are no notifications to distract you.

Notebook 3 - The Organizer

In this notebook I focus on the task of organizing my year, month, and weeks. This is where the planning process begins before being transferred to the Daily Planner. It is important to note that this notebook is meant to be a workspace and not necessarily something that will be referred back to in the future.

I use this notebook to jot down bullet points, to-do lists, and diagrams that help me create structure for my projects and plans. It is also where I keep timelines and roadmaps for my projects. The main focus of this notebook is on figuring out what steps I need to take to reach my daily, weekly, monthly, quarterly, yearly, and long-term goals.

I keep this notebook at home and use it as a tool for fleshing out plans. If I am out and have ideas, I record them in one of my other notebooks. The Organizer is designated by its red cover and is meant to be used as a workspace.

Notebook 4 - The Pocket EDC

The goal for this notebook (similar to the red organizer) is for it to be a temporary place. Nothing important should live here. Many important ideas or plans might start here, but they should not end here.

Since you’ll have this notebook with you all the time, it will be filled with a random assortment of stuff. This means you will never go to this notebook with confidence to find something.

You need to migrate value out of this notebook into a permanent space. That could be your Hulk, or your planner, or any other tool (calendar, to-do app, etc).

The EDC is your faithful companion. Your adventurous friend always willing to go anywhere and everywhere. Take it with you when you don’t know what to expect and you will have a faithful companion.

This notebook should be thin and flexible so you never have to think twice about bringing it with you or not. Yes, you want to bring it with you.

Conclusion

Is using four notebooks overkill? Maybe. But it has been a game-changer for me in terms of staying organized and on top of my tasks and notes. Each notebook serves a specific and essential purpose in my productivity journey.

January 9, 2023 · #writing

writing
January 8, 2023

Freeform journaling: How to Embrace the Mess and Find Value in Your Notes

Freeform journaling

“Freeform journaling” is a term I use to describe my journaling practice. It involves capturing everything, both valuable and seemingly insignificant notes, without hesitation or worry.

One of the benefits of this approach is that it allows me to be more free and spontaneous with my writing habit. I never have to worry about whether or not something is worth recording in my journal because I know that everything goes in there.

The first step of freeform journaling is simply capturing your thoughts and ideas on paper. This can be as simple as writing down everything that comes to mind without worrying about organization or structure.

From there, you can move on to the second step: processing the value of your notes. This might involve identifying valuable ideas, labeling them, categorizing them, and eventually archiving them for future reference.

While “freeform journaling” doesn’t necessarily mean messy journaling, it does involve letting go of perfectionism and allowing yourself the freedom to write whatever comes to mind. This can be liberating and inspiring, and it can also lead to more creative ideas and insights.

January 8, 2023 · #writing

writing
January 7, 2023

Maximize the Value of Your Journal Notes: 5 Simple Steps to Follow

Maximize the Value of Your Journal Notes

As a writer, I often journal my thoughts and ideas. But sometimes, I find myself overwhelmed with too much content that doesn’t have any real value. That’s why I’ve developed a process for extracting value out of my journal notes.

  1. Scan pages: First, I scan through my journal pages and mark any that don’t have any value with a big black cross in the corner. This helps me quickly skip over pages that don’t have anything of interest.

  2. Mark content: Next, I label sections of valuable content in a different color. I only mark the headline of the content, so I can easily find it later. For example, I might use a red pen to underline a title.

  3. Process the content: Then, I process the valuable content. If it’s a draft, I might rewrite it for clarity. If it’s the seed of an idea or project, I flesh it out in more detail.

  4. Migrate the content: After that, I migrate the content to its proper place. For instance, to-dos go into an app or planner, quotes go into a text file, and article ideas go into the draft folder of my blog. However, my daily driver notebook (which I call “the Hulk”) is where I keep early concepts and project ideas, so I don’t move them anywhere else.

  5. Archive the content: Finally, I archive the content by letting it live where it is or by going back through the previous steps to make sure I’ve properly processed and migrated the information.

It’s important to build a habit of getting value out of your finished journals. By following this process, you can make sure that you’re not wasting your time on content that doesn’t matter and that you can easily find and use the valuable content when you need it.

January 7, 2023 · #writing

work life
January 6, 2023

The 1-Month Project Plan to Boost Your Productivity: A Guide

The 1-Month Project Plan

When working on creative projects (anything that involves creating something, such as cooking, building, painting, or coding), I recommend setting up plans that are one month in duration.

I am a big advocate of 12-week-year project planning1. It’s a great middle ground between long-term planning (more than a year into the future) and short-term planning (one week or month ahead). 12-week planning allows you to allocate enough time to make significant progress, while still being able to keep the entire project in mind.

So, why consider a 1-month project plan instead? One-month and 12-month plans are not mutually exclusive, but they focus on different aspects of achieving goals. I like to aggressively time-box goals to force myself to make tough decisions early on. With too much time, we may be tempted to increase the scope of our project beyond our capabilities.

A 1-month project plan is focused on creating a viable, complete, and self-contained results within a short timeline.2 This doesn’t mean that the final product will be finished in one month (for that, we rely on the 12-week plan), but it does mean that we will have something complete and end-to-end by the end of the month.

Benefits

So, why do this at all? Here are some reasons I can think of:

However, don’t get caught in the trap of process over progress. Pilot new methods without committing to them. Take what works for you, adapt it, incorporate it into your own processes, and move on.

Above all, always be creating.


  1. The 12 week plan is based on a book called The 12 Week Year by Brian Moran and Michael Lennington. It’s all about setting goals and objectives for a 12-week period and then breaking them down into weekly tasks.↩

  2. Aka “Minimum Viable Product”↩

January 6, 2023 · #work life

mindfulness
January 5, 2023

The Power of the Regular Brain-Dump

The Power of the Regular Brain-Dump

As someone who has struggled with anxiety and feeling overwhelmed, I have found that one of the most effective ways to calm my nerves and center myself is through a brain dump.

For those unfamiliar, a brain dump is simply the act of getting all of your unstructured, unorganized thoughts onto paper through free-writing. It’s not about creating a finished product, but rather about getting everything out of your head and onto paper.

I find that when I’m feeling anxious or tense, I have a million different thoughts racing through my mind. Some of these thoughts are fully formed, but many times they are just emotions that need to be processed, plans that are still being developed, or unconnected ideas that are clouding my judgment.

The goal of a brain dump is to free up your mental bandwidth by getting all of these thoughts out of your head and onto paper. And the best part is, you don’t even have to worry about what you wrote afterward. If there’s something you want to act on, you can save it in a journal or add it to your to-do list. But if not, you can simply let it go and move on.

But you don’t have to wait for a crisis to do a brain dump. Regular brain dumps can serve as a form of mindfulness, similar to journaling or meditation.

So next time you’re feeling overwhelmed or stressed out, try doing a brain dump. You might be surprised at how much better you feel.

January 5, 2023 · #mindfulness

robots
January 4, 2023

The Dehumanization of Decision Making: Why It’s Time to Reclaim Our Individuality from Institutions

The Dehumanization of Decision Making

Have you ever stopped to consider just how much control institutions have over our lives? They dictate where we go to school, what we do for work, and even how we spend our free time. Institutions have become the dominant force in society, shaping the way we think and act.

But what is an institution? At its core, it is a form of emerging intelligence - a collective entity that makes decisions and shapes our lives. We have given full control of our lives to these institutions, delegating our responsibilities to them.

But this kind of decision making can be dehumanizing. Instead of being guided by our own intelligence and humanity, we are led by the madness of crowds. We become nothing more than a cog in the machine, following orders and marching in lockstep with the rest of society.

This is not to say that institutions are inherently bad. They serve a crucial role in society, coordinating and organizing our collective efforts. But we need to be mindful of the impact they have on our individual experiences and decision making.

Successful communities, particularly close-knit ones, reinforce collaboration and the human touch. These communities recognize the value of the individual experience and encourage people to think and act independently.

As we continue to develop artificial intelligence and further segregate organizational decision making from humanity, it’s important to consider where the value of the individual experience lies among the crowds. Do we want to continue down this path of dehumanization, or do we want to find ways to incorporate more humanity into our decision making processes? The choice is ours.

January 4, 2023 · #robots

mindfulness
January 3, 2023

The Constant Pressure to Be Perfect: How to Cope and Find Relief

The Constant Pressure to Be Perfect

The weight of perfection is suffocating, constantly bearing down on me and never letting up. But through mindfulness and self-reflection, I’ve learned to navigate the overwhelming pressure and find moments of peace.

To cope with this pressure, I try to observe the situation objectively and calmly. I take a deep breath and focus on the present moment, trying to remove any excitement or drama from my analysis. Most of the time, things are under control or there is a clear solution to the problem at hand.

Journaling or writing posts like this one can also help relieve some of the pressure. It’s a matter of mind over matter - by writing about my anxiety, I can help to dissipate it.

This process of detachment and observation is a form of mindfulness. It doesn’t always feel like mindfulness when I’m sweating from the pressures of work and trying to objectively assess the situation. It feels more like a technique that should be taught in MBA programs rather than meditation retreats.

But hey, at least I’m not alone in this battle against the pressure to be perfect. We all have our own inner demons to fight and our own unique ways of coping. And who knows, maybe one day we’ll all become so zen that we can laugh in the face of perfectionism (or at least chuckle softly to ourselves). Until then, let’s keep taking deep breaths and reminding ourselves that it’s okay to be human.

January 3, 2023 · #mindfulness

work life
January 2, 2023

Leadership and Art: 5 Keys to Success in Either Field

  1. Stick to your principles, even when it’s tough.
  2. Don’t cut corners. Do things the right way, even if it’s harder or takes longer.
  3. Do the right thing without compromise. Act according to your values and beliefs.
  4. Don’t give up when things get tough. Stay resilient and determined.
  5. Be true to yourself and your values. Be transparent and consistent in your actions.

Leadership and Art

January 2, 2023 · #work life

January 1, 2023

The Healing Power of Creativity: How Crafting and Labor Bring Order to Chaos and Peace to the Soul

The soul-lifting power of creativity, craft, and labor comes from the fact that the products of these activities exist outside of ourselves. By focusing on outputs we are forced to shift our attention to the external world, and away from us and our ego.

There is a peace that comes from completing a project, painting a picture, fixing a broken shelf, volunteering
 All of them bring our conscience into the world, away from us.

The ego is the enemy and the source of much of our suffering. Creativity, in the widest sense of the world (meaning creating anything, making anything tangible), is a remedy to our suffering.

Creating in any of its forms (cooking, journaling, building, fixing,
) is human ingenuity working to put order in the world to make sense of the chaos around us.

This is the meaning of a well-lived life. To bring order where there’s chaos. To create.

We suffer because of the chaos within, we regain peace when we create and put order back out into the world.

January 1, 2023 · #miscellaneous

writing
December 31, 2022

Don’t Be Afraid to Mark Up Your Books: Why Underlining and Annotating Is Actually a Good Thing

Are you guilty of avoiding underlining and annotating your books because you’re afraid of damaging their resale value or simply out of respect for the physical object? Well, it’s time to embrace your inner reader and start marking up those pages!

Reading a book is a deeply personal experience, and for many of us, the act of physically interacting with the text is an important part of the process. Whether it’s underlining passages, writing notes in the margins, or simply dog-earing the pages, our physical interactions with a book can help us remember and retain the information we’re reading.

Interacting with a text physically by underlining passages and writing notes in the margins can actually be a way of honoring the spirit of the book. It shows that you are actively participating in the conversation the author is trying to have with you and expressing your own thoughts and ideas. Plus, creating a lasting record of your own thoughts and experiences through annotations can be just as valuable as the book itself.

When we engage with a text in this way, we actively participating in the conversation the author is trying to have with us. We are expressing our own thoughts and ideas, and in doing so, we are contributing to the ongoing dialogue that surrounds a book.

So go ahead and mark up those pages. Protecting books is important, but there’s no reason to be afraid of physically engaging with them. Happy reading!

December 31, 2022 · #writing

December 30, 2022

Step-By-Step Guide To Setting up Vial for the Planck on macOS

(Part 3 of Step-By-Step Guide To Configuring Your Planck Using QMK, VIA and Vial on macOS)


You need to setup VIA for macOS as described in the previous posts in order to get Vial up and running.

This guide is organized in four parts:

(The official full detailed instructions can be found in the Vial user guide: Porting a VIA keyboard to Vial)

Part 1 Setup the Vial keymap directory

1.1 Clone the Vial QMK fork

Start by forking your own copy of Vial repository https://github.com/vial-kb/vial-qmk via github’s interface.

Clone your fork of the Vial repo. You will need the HTTPS url (eg: https://github.com/<github_username>/vial-qmk.git).

git clone --recurse-submodules https://github.com/<github_username>/vial-qmk.git

1.2 Create a new vial keymap

Copy the existing keymaps/viafolder from <folder>/vial-qmk/keyboards/planck/keymaps/via to <folder>/vial-qmk/keyboards/planck/keymaps/vial.

1.3 Enable Vial

In your <folder>/vial-qmk/keyboards/planck/keymaps/vial/rules.mk, after the line VIA_ENABLE = yes add the following:

VIAL_ENABLE = yes

1.4 Create a KLE for VIA

via: https://get.vial.today/docs/porting-to-via.html#3-create-a-kle-for-via

For the planck this is what that looks like:

["0,0","0,1","0,2","0,3","0,4","0,5","0,6","0,7","0,8","0,9","0,10","0,11"],
["1,0","1,1","1,2","1,3","1,4","1,5","1,6","1,7","1,8","1,9","1,10","1,11"],
["2,0","2,1","2,2","2,3","2,4","2,5","2,6","2,7","2,8","2,9","2,10","2,11"],
["3,0","3,1","3,2","3,3","3,4","3,5","3,6","3,7","3,8","3,9","3,10","3,11"]

1.5 Create a JSON for VIA

Fill out the following JSON template:

{
    "name": "",
    "vendorId": "",
    "productId": "",
    "lighting": "none",
    "matrix": {
        "rows": 0,
        "cols": 0
    },
    "layouts": {
        "labels":
        "keymap":
    }
}

See details at Vial site Create a JSON for VIA

In the case of a Planck this would seem to be the layout of the keys

[
 ["0,0","0,1","0,2","0,3","0,4","0,5","0,6","0,7","0,8","0,9","0,10","0,11"],
 ["1,0","1,1","1,2","1,3","1,4","1,5","1,6","1,7","1,8","1,9","1,10","1,11"],
 ["2,0","2,1","2,2","2,3","2,4","2,5","2,6","2,7","2,8","2,9","2,10","2,11"],
 ["3,0","3,1","3,2","3,3","3,4","3,5","3,6","3,7","3,8","3,9","3,10","3,11"]
]

However the true layout of the keys is closer to this:

[
   [ "0,0", "0,1", "0,2", "0,3", "0,4", "0,5",
     "4,0", "4,1", "4,2", "4,3", "4,4", "4,5" ],
   [ "1,0", "1,1", "1,2", "1,3", "1,4", "1,5",
     "5,0", "5,1", "5,2", "5,3", "5,4", "5,5" ],
   [ "2,0", "2,1", "2,2", "2,3", "2,4", "2,5",
     "6,0", "6,1", "6,2", "6,3", "6,4", "6,5" ],
   [ "3,0", "3,1", "3,2",
     "7,3", "7,4", "7,5", "7,0", "7,1", "7,2",
     "3,3", "3,4", "3,5" ]
]

Here is the final vial.json file including two alternative layouts for the bottom row:

{
 "name": "Planck",
 "vendorId": "0x03A8",
 "productId": "0xA4F9",
 "lighting": "none",
 "matrix": {
  "rows": 8,
  "cols": 6
 },
 "layouts": {
  "labels": [
   ["Bottom Row", "1x2uC", "4x12", "2x2u"]
  ],
  "keymap": [
   [
    { "c": "#aaaaaa" },
    "0,0",
    { "c": "#cccccc" },
    "0,1", "0,2", "0,3", "0,4", "0,5",
    "4,0", "4,1", "4,2", "4,3", "4,4",
    { "c": "#aaaaaa" },
    "4,5"
   ],
   [
    "1,0",
    { "c": "#cccccc" },
    "1,1", "1,2", "1,3", "1,4", "1,5",
    "5,0", "5,1", "5,2", "5,3", "5,4",
    { "c": "#aaaaaa" },
    "5,5"
   ],
   [
    "2,0",
    { "c": "#cccccc" },
    "2,1", "2,2", "2,3", "2,4", "2,5",
    "6,0", "6,1", "6,2", "6,3", "6,4",
    { "c": "#aaaaaa" },
    "6,5"
   ],
   [
    "3,0", "3,1", "3,2",
    "7,3",
    { "c": "#777777" },
    "7,4\n\n\n0,0",
    { "c": "#cccccc", "w": 2 },
    "7,0\n\n\n0,0",
    { "c": "#777777" },
    "7,1\n\n\n0,0",
    {"c": "#aaaaaa" },
    "7,2",
    "3,3", "3,4", "3,5"
   ],
   [
    {"y": 0.25, "x": 4, "c": "#777777" },
    "7,4\n\n\n0,1",
    {"c": "#cccccc" },
    "7,5\n\n\n0,1",
    "7,0\n\n\n0,1",
    { "c": "#777777" },
    "7,1\n\n\n0,1"
   ],
   { 
    "x": 4, "c": "#cccccc", "w": 2 },
    "7,5\n\n\n0,2",
    { "w": 2 },
    "7,1\n\n\n0,2"
   ]
  ]
 }
}

1.6 Save the new vial.json file

Place the generated VIA JSON under <folder>/vial-qmk/keyboards/planck/keymaps/vial/vial.json so that Vial build process can find it.

This file is the KLE compatible layout configuration that is stored directly in the keyboard.

1.7 Create a new config.h file

Start by generating a unique keyboard ID as follows. From the root of <folder>/vial-qmk/, run the following command to generate a unique Vial keyboard ID:

python3 util/vial_generate_keyboard_uid.py

Copy the generated output. Eg:

#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}

Next create a new file config.h inside <folder>/vial-qmk/keyboards/planck/keymaps/vial/. Add the following contents to it (the last line must match the output generated above)

/* SPDX-License-Identifier: GPL-2.0-or-later */

#pragma once

#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}

1.8 Set up secury lock

In order to protect your keyboard from an attach coming from a machine it is connected to, Vial requires the user to unlocks the keyboard the first time it is connected to a computer.

This security feature can be disabled, but it is easy enough to setup and use so we will leave it in.

Pick a combo of at least 2 keys, and take note of the key location on your keyboard.

In my case I’ll choose Esc (located at [0, 1]) and Return (located at [2, 11]) on my planck.

Add the following lines to your config.h file right below the VIAL_KEYBOARD_UID line:

#define VIAL_UNLOCK_COMBO_ROWS { 0, 1 }
#define VIAL_UNLOCK_COMBO_COLS { 2, 11 }

Part 2 Build the Vial firmware

If you have followed the previous setup for QMK and VIA this should be straighforward.

You can compile Vial by doing:

qmk compile -kb planck/rev6 -km vial

or

make planck/rev6:vial

You might see output like this:

Creating binary load file for flashing: .build/planck_rev6_vial.bin                                 [OK]
Creating load file for flashing: .build/planck_rev6_vial.hex                                        [OK]

Size after:
   text    data     bss     dec     hex filename
      0   49396       0   49396    c0f4 .build/planck_rev6_vial.hex

Copying planck_rev6_vial.bin to qmk_firmware folder                                                 [OK]
(Firmware size check does not yet support cortex-m4 microprocessors; skipping.)

Here is the generated file:

planck_rev6_vial.bin

Part 3 Flash the Vial firmware

Follow the same process as if flashing any other QMK firmware. You can see full details in the previous guide: Step-By-Step Guide To Setting up QMK for the Planck on macOS.

3.1 Enter bootloader mode

With our planck keyboard we press key combo raise+lower+q (or press the reset button). With the QMK Toolbox open we can see status logs.

*** STM32 DFU device connected: STMicroelectronics STM32 BOOTLOADER (0483:DF11:2200)

3.2 Open the VIA Keymap Firmware with QMK Toolbox

Open the VIA firmware file in QMK Toolbox. It can be found on the root /qmk_firmware/ folder. In my case:

planck_rev6_vial.bin

3.3 Flash Your Keyboard

Click the Flash button in QMK Toolbox.

Here is my output in all it’s glory:

*** Attempting to flash, please don't remove device
[...]
 Erase done.
[...]
 Download done.
 File downloaded successfully
 Transitioning to dfuMANIFEST state
*** STM32 DFU device disconnected: STMicroelectronics STM32 BOOTLOADER (0483:DF11:2200)

Part 4 Edit the keymal with Vial

That’s it for setting up VIAL. Now we are ready to use the visual GUI to edit the keymap.

4.1 Download the Vial editor

Download the GUI from their site: Download Vial. For mac the file is Vial-v0.4.1.dmg

4.2 Open the Vial app

As with VIA macOs will likely throw you a security alert. Go to your security settings to open the app. (Always make sure you trust and understand what you download from the internet.)

The connected keyboard should load. If it doesn’t click the Refresh button.

4.3 Configure your keyboard

From here on out the workflow is the same as with VIA. Any changes you do in the UI app will reflect right away in your keyboard. No compilation. No flashing.

Keep in mind that you can’t use VIA and Vial at the same time.

Enjoy and have fun! đŸ„‚

December 30, 2022

View the archives