Documentation/issue #582 edit readme.md by courtneyludick · Pull Request #585 · PubInv/krake

courtneyludick · 2026-07-13T20:09:21Z

Links

Closes Documentation, Make the main README.md "Sell the Krake" #582

Artifacts (attach if relevant)

edits to readme.md

Checklist

check for ? in documentation

GPAP completion
Comparison of rev1 & rev2

Added initial content and structure for README2.md.

Added OSHWA certification details and related links.

Added references and further reading section to README2.

Added credits and mentorship information for the Krake project.

Added detailed features and specifications for the Krake wireless alarm device.

Expanded the README with detailed sections on features, hardware, firmware, and contributing guidelines. Updated the quick start instructions and added links to user and developer manuals.

Updated description of the Krake alarm device to clarify its customizable features.

Added a section explaining how the Krake alarm device works.

Added detailed navigation and settings information for the LCD UI, including planned layout, rotary encoder actions, and alarm actions. Updated credits and certification information.

Updated the README2.md to include purchasing information, build instructions, and detailed speaker specifications.

Clarified the quick start section and fixed typos.

Added licensing information for firmware and hardware.

Updated README to reflect new branding and added detailed descriptions of features and functionalities. TBC/ TBD: GPAP complete response removal of : mockingkrake esp32-wroom-32d firmware development resources

TBC comparison of rev1 & 2

ForrestErickson

This is Lee's first pass only. I became fatigued before finishing.

ForrestErickson · 2026-07-15T17:28:58Z


-# Krake™ rev2
+#### How it works?
+1. Condition detected- A sensor triggers an alarm event


Regarding, " Condition detected- A sensor triggers an alarm event" The visitor will not clearly understand "who" is doing the detection. The Krake?

We have limited time (words) to get the visitor to understand that Krake is part of a system with other devices. The Krake is added to such systems so that a device (Example gate opening sensor) wanting to alert a human of condition uses the Krake to announce the alarm.

I would disagree here- the use cases are explained further down this is a very broad overview designed to allow the reader to think how krake could fit into their use case before we introduce them to some (allowing them to shape an idea without our input) . a potential rewording i think 'who' is made clear by 'a sensor' but perhaps rewording this to say
" A condition is detected by an external sensor that relays this information to Krake to trigger an alarm event'"

ForrestErickson · 2026-07-15T17:33:52Z

-# Krake™ rev2
+#### How it works?
+1. Condition detected- A sensor triggers an alarm event
+2. Krake Receives it- Alert arrives wirelessly via MQTT over local network or internet


Note the passive voice in this sentence. I think that warns of the opportunity for confusing. We should be heading off such confusion.

Illistrate with an example.

For example a gate open sensor on a security system publishes a message and MQTT message to the Krake, or by direct RS232 connection writes a message to the Krake.

In the use case i think this would be appropriate but in this brief non-technical overview on how it works i think it is too much information

ForrestErickson · 2026-07-15T17:37:30Z

+#### How it works?
+1. Condition detected- A sensor triggers an alarm event
+2. Krake Receives it- Alert arrives wirelessly via MQTT over local network or internet
+3. You're alerted- Lights flash, audio plays and acknowledgement is sent back


The Krake makes sound, lights some LEDs and displays on the LCD a message to the user.

With the Rotary encoder the user can react to the alarm, {Ack, Dismiss , Shelve, or Complete}
With the Mute button the user can temporarily mute the audio message for some alarm fatigue relief.

ForrestErickson · 2026-07-15T17:48:39Z

-At startup, saved-network retries and the fallback WiFiManager recovery portal are time-bounded so a missing or invalid configuration cannot indefinitely block the Krake hardware loop.
+## About Krake & Example Use Cases
+The hope was to develop the initial design for a wireless alarm device to alert nearby parties of a particular state. 
+We developed the name of this invention team based on a Crake: a bird with a distinctive, slightly alarming cry. We changed the spelling as a joke. “Flaycrake” is an old term for a scarecrow, which also aligned with our mission.


Change to something like:

About the name, Krake,
The inspiration for the invention name is based on a Crake: a bird with a distinctive, slightly alarming cry. We changed the spelling so as to have a unique name and still preserve the humor .

ForrestErickson · 2026-07-15T17:54:46Z

+| Feature    | Details |
+| -------- | ------- |
+| Customiseable audio  |WAV and MP3 playback, Alarm-level-specific audio, Adjustable volume,SD-card-based audio storage, Busy-line monitoring and Runtime diagnostics   |
+| LCD User Interface & Rotary Knob    | 20 x 4 I²C LCD interface integrated with a rotary encoder and custom menu system to navigate settings without the need for an external device.  Real-time alarm display, Alarm queue indication, Wi-Fi status indication, MQTT broker status indication, Volume and mute display and Alarm acknowledgement actions |


There is a lot here a visitor will not understand.
Also things not fully tested.

Regarding, " Alarm queue indication" What would a three deep queue look like and how could we produce it now (15 July 2026)?

unsure - this information is moved from the original readme - no new information was added

ForrestErickson · 2026-07-15T17:56:21Z

+| LED Annunciation  | Variety of LED levels  including steady or blinking deisgned to be visible across a room    |
+| Flexible Power    | USB-C, 2.1mm center-positive barrel connector or RJ12 SPI interface power jumpers    |
+| Wi-Fi Connectivity    | Acts as a Wi-Fi station connected to a local network enabling alerts locally or via internet, captive portal set up, storage of multiple Wi-Fi credentials, automatic reconnection, OTA firmware updates and Network status display   |
+| MQTT Protocol    | MQTT alarm subscriptions, GPAP response publishing, Alarm acknowledgements, Alarm dismissal and shelving, Device monitoring, Configurable topic subscriptions and MQTT status display on LCD    |


Here "GPAP " is introduced without explanation.

i suggest we use ' general purpose alarm protocol' instead of GPAP if this is a concern. I dont think explaining GPAP in the read me for krake is a good use of the document nor a match for the purpose of the read me

there is actually a link to GPAP included in the further reading section so i think that covers the mention of it here without taking away from the Krake

ForrestErickson · 2026-07-15T17:59:41Z

+
+
+## Firmware
 | Module               | Purpose                            |


Do we need this on the main Readme?

unsure- was in the original readme

Put images initial images side by side

Updated product description and clarified device features.

Added an introductory paragraph about the Krake alarm device.

Revised the explanation of the name 'Krake' for clarity and humor.

Separated 'About Krake' and 'Example Use Cases' into distinct sections for clarity.

Enhanced the explanation of how the device works, providing more detail on sensor detection and user interaction with alarms.

courtneyludick and others added 22 commits July 13, 2026 18:14

Create README2.md

67c2439

Create README2.md with project overview and sections

3f7e92f

Added initial content and structure for README2.md.

Update README2 with OSHWA certification information

c66fd52

Added OSHWA certification details and related links.

Update README2 with references and manuals

e595872

Added references and further reading section to README2.

Add image to README2 and update pitch text

fd1244e

Update README2 with credits and mentorship details

8d442a5

Added credits and mentorship information for the Krake project.

Enhance README2 with Krake features and overview

9494638

Added detailed features and specifications for the Krake wireless alarm device.

Enhance README with features and documentation

3b36625

Expanded the README with detailed sections on features, hardware, firmware, and contributing guidelines. Updated the quick start instructions and added links to user and developer manuals.

Enhance Krake description for clarity and detail

91e839c

Updated description of the Krake alarm device to clarify its customizable features.

Add 'How it works?' section to README2.md

31ee91e

Added a section explaining how the Krake alarm device works.

Enhance README with LCD UI details and credits

5f771b9

Added detailed navigation and settings information for the LCD UI, including planned layout, rotary encoder actions, and alarm actions. Updated credits and certification information.

Enhance README2 with new sections and details

6baf510

Updated the README2.md to include purchasing information, build instructions, and detailed speaker specifications.

Update README2.md

a1a0fc1

Update README2.md for clarity and corrections

3e6a01d

Clarified the quick start section and fixed typos.

Update README2.md

41c2cef

Update README2.md

b2c4797

Add license section to README2.md

f6e1030

Added licensing information for firmware and hardware.

Add hardware license information to README2.md

fb247fc

Revise README for branding and feature updates

b2d40fb

Updated README to reflect new branding and added detailed descriptions of features and functionalities. TBC/ TBD: GPAP complete response removal of : mockingkrake esp32-wroom-32d firmware development resources

Fix formatting issues in README.md

46740ae

TBC comparison of rev1 & 2

Delete README2.md

1952d21

Bump GPAD firmware version

0651171

nk25719 requested review from ForrestErickson and nk25719 July 15, 2026 17:14

ForrestErickson requested changes Jul 15, 2026

View reviewed changes

courtneyludick added 5 commits July 20, 2026 15:59

Enhance README with images and formatting

c893ced

Put images initial images side by side

Revise Krake product description in README

65d2df9

Updated product description and clarified device features.

Enhance README with product introduction

426313f

Added an introductory paragraph about the Krake alarm device.

Clarify the origin of the name 'Krake'

edb8436

Revised the explanation of the name 'Krake' for clarity and humor.

Refactor README sections for clarity

470c551

Separated 'About Krake' and 'Example Use Cases' into distinct sections for clarity.

Revise 'How it works' section for clarity and detail

a812e26

Enhanced the explanation of how the device works, providing more detail on sensor detection and user interaction with alarms.

Uh oh!

Conversation

courtneyludick commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Links

Artifacts (attach if relevant)

Checklist

Uh oh!

ForrestErickson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

courtneyludick commented Jul 13, 2026 •

edited

Loading