{"id":13576578,"url":"https://github.com/softmoth/rotary_encoder","last_synced_at":"2025-04-10T01:16:37.646Z","repository":{"id":147469866,"uuid":"326870521","full_name":"softmoth/rotary_encoder","owner":"softmoth","description":"Library for reading rotary encoders from a micro-controller unit","archived":false,"fork":false,"pushed_at":"2021-01-06T17:46:00.000Z","size":20,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T01:16:33.150Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softmoth.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-01-05T03:03:05.000Z","updated_at":"2022-11-17T12:15:11.000Z","dependencies_parsed_at":"2023-07-24T18:30:39.579Z","dependency_job_id":null,"html_url":"https://github.com/softmoth/rotary_encoder","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softmoth%2Frotary_encoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softmoth%2Frotary_encoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softmoth%2Frotary_encoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softmoth%2Frotary_encoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softmoth","download_url":"https://codeload.github.com/softmoth/rotary_encoder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137887,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:01:11.688Z","updated_at":"2025-04-10T01:16:37.600Z","avatar_url":"https://github.com/softmoth.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"= rotary_encoder\n:toc: preamble\n:issues: https://github.com/softmoth/rotary_encoder/issues\n:license: https://github.com/softmoth/rotary_encoder/blob/master/LICENSE\n\nLibrary for reading rotary encoders from a micro-controller unit\n\n== Features\n\nThis library is very much inspired by the code \u0026 ideas found at http://www.buxtronix.net/2011/10/rotary-encoders-done-properly.html. That means it handles debouncing the signal robustly in software, and should work well with even noisy, low-quality encoders.\n\nIt is written in ANSI C, with no exernal dependencies, so it is suitable for any micro-controller unit and any development environment. It does not require Arduino libraries.\n\n=== Encoder types\n\nAn application can define and use multiple encoders. Each encoder can be one of three types:\n\n* *Full-step* encoders move through a full 4 states with each detent, and stop with voltage high on both pins.\n* *Half-step* encoders move through 2 of the 4 states with each detent, stopping with voltage high on both pins or low on both pins.\n* *Tristate* encoders move through 3 states rather than 4.\n\n== Installation\n\nThe library is ANSI C code with no external dependencies, and should compile\nwith any compiler for any environment. Simply copy rotary_encoder.c and\nrotary_encoder.h into your project as you would any other source files.\n\n== Examples\n\n=== `skeleton`\n[source,c]\n----\n#include \"rotary_encoder.h\"\n\n#define READ_ENCODER_PINS(pin1, pin2) \\\n            (digitalRead(pin1) | (digitalRead(pin2) \u003c\u003c 1))\n\n/* Simple counter to track the number of turns */\nint Counter = 0;\n\n/* Define an encoder */\n#define ENCODER_PIN_A 8\n#define ENCODER_PIN_B 9\nstatic rotenc_encoder_t Encoder = ROTENC_FULL_STEP_INIT;\n\nvoid process_encoder(void) {\n    Counter += rotenc_process_pins(\u0026Encoder,\n                    READ_ENCODER_PINS(ENCODER_PIN_A, ENCODER_PIN_B));\n}\n\nint main(void)\n{\n    /* Loop */\n    while (1) {\n        process_encoder();  /* Poll periodically */\n\n        /* Now, do something with Counter */\n        exit(0);\n    }\n}\n----\n\n=== `simulation`\n\nThe `examples/simulation` program, handy when developing the library itself, requires the `curses` library for terminal input. This is likely to work on Unix and OS X systems.\n\n== Reference\n\n=== Initialization\n\nSimply define a variable of type `rotenc_encoder_t`, and initialize it with the appropriate macro for the \u003c\u003cEncoder types,type\u003e\u003e of encoder.\n[source,c]\nrotenc_encoder_t encoder1 = ROTENC_FULL_STEP_INIT;\nrotenc_encoder_t encoder2 = ROTENC_HALF_STEP_INIT;\nrotenc_encoder_t encoder3 = ROTENC_TRISTATE_INIT;\n\n=== Processing updates\n\nRegardless of whether you set up interrupts on pin changes or poll the pins in a loop, the processing is the same.\n\n[source,c]\n    /* pins is an integer between 0 and 3. If both encoder pins     are high, pins == 3. If both are low, pins == 0. */\n    unsigned char pins = READ_ENCODER_PINS(ENCODER_PIN_A, ENCODER_PIN_B);\n    signed char rotation = rotenc_process_pins(\u0026encoder1, pins);\n\nA few notes on this example:\n\n* `READ_ENCODER_PINS` is something you will need to provide; see the `examples/skeleton.c` \u003c\u003cExamples,example\u003e\u003e for a hint in the right direction.\n* `ENCODER_PIN_A` and `ENCODER_PIN_B`, of course, depend on how you've connected the encoder to the MCU. It can be hard to know which order the pins go in; if your encoder is registering the wrong direction, just swap the wires.\n* `rotation` is `-1` if the encoder moved left, `+1` if right, and `0` if there was a partial move, bouncing, or any invalid input.\n\n=== Removing unused encoder types\n\nIf you only use one or two encoder types, you can remove the unused state tables:\n\n[source,c]\n/* Define only the wanted types */\n#define ROTENC_FULL_STEP\n#define ROTENC_HALF_STEP\n#define ROTENC_TRISTATE\n#include \"rotary_encoder.h\"\n\n== Bugs\n\nIf you find this doesn't work with your development environment, please {issues}[open an issue].\n\n== License\n\n[subs=+macros]\n----\n/* Copyright 2021 Tim Siegel \u003csiegeltr@gmail.com\u003e\n * Licenced under the https://github.com/softmoth/rotary_encoder/blob/master/LICENSE[GNU GPL Version 3]\n\n * Portions of this code derived from\n * https://github.com/buxtronix/arduino/tree/master/libraries/Rotary[https://github.com/buxtronix/arduino/]:\n * Copyright 2011 Ben Buxton. Licenced under the GNU GPL Version 3.\n */\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftmoth%2Frotary_encoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftmoth%2Frotary_encoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftmoth%2Frotary_encoder/lists"}