{"id":20763991,"url":"https://github.com/umutsevdi/unix-assistant","last_synced_at":"2025-10-13T03:06:45.711Z","repository":{"id":65047241,"uuid":"573442348","full_name":"umutsevdi/unix-assistant","owner":"umutsevdi","description":"A voice assistant tool for running shell commands","archived":false,"fork":false,"pushed_at":"2023-04-05T13:18:02.000Z","size":1351,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T18:55:19.923Z","etag":null,"topics":["linux","linux-shell","oled","oled-display-ssd1306","speech-to-text"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umutsevdi.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2022-12-02T13:26:38.000Z","updated_at":"2023-01-31T21:31:39.000Z","dependencies_parsed_at":"2023-01-01T04:21:54.255Z","dependency_job_id":null,"html_url":"https://github.com/umutsevdi/unix-assistant","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/umutsevdi/unix-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umutsevdi%2Funix-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umutsevdi%2Funix-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umutsevdi%2Funix-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umutsevdi%2Funix-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umutsevdi","download_url":"https://codeload.github.com/umutsevdi/unix-assistant/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umutsevdi%2Funix-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014166,"owners_count":26085369,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["linux","linux-shell","oled","oled-display-ssd1306","speech-to-text"],"created_at":"2024-11-17T10:48:15.682Z","updated_at":"2025-10-13T03:06:45.669Z","avatar_url":"https://github.com/umutsevdi.png","language":"C++","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/umutsevdi/unix-assistant\"\u003e\n  \u003ch3 align=\"center\"\u003e Unix Assistant\u003c/h3\u003e\n  \u003c/a\u003e\n\n\u003cp align=\"center\"\u003e  \nA voice assistant tool on OLED displays for running shell commands\n  \u003cbr/\u003e\n    \u003ci\u003eDeveloped by \u003ca href=\"https://github.com/umutsevdi\"\u003e Umut Sevdi\u003c/a\u003e,\n    \u003ca href=\"https://github.com/Selimshady\"\u003eYavuz Selim Cagan\u003c/a\u003e,\n    \u003ca href=\"https://github.com/semihyazici\"\u003eSemih Yazici\u003c/a\u003e and\n    \u003ca href=\"https://github.com/Oguzhanercan\"\u003eOguzhan Ercan\u003c/a\u003e.\u003c/i\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"doc/GS_proje_rapor.pdf\"\u003e\u003cstrong\u003eExplore the docs »\n\u003c/strong\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003cdetails open=\"open\"\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\u003ca href=\"#project_definition\"\u003eProject Definition\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#system_architecture\"\u003eSystem Architecture\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#hardware\"\u003eHardware Requirements\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"LICENSE\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"screenshot/program1.png\" width=512px\u003e\u003c/p\u003e\n\n\u003cp id=\"project_definition\"\u003e\n\n## 1. Project Definition\n\nUnix Assistant is a voice controlled UNIX Shell that is displayed on the OLED screens.\nWorks on Raspberry Pi or any embedded device running UNIX like operating systems.\n\nIn our project we used Raspberry Pi Zero running [Rasbian](https://www.raspberrypi.com/software/).\n\nBy clicking to the button, our software records the voice and converts it into a\nvalid UNIX shell command. After that our software executes the command and displays\nit's output on OLED screen.\n\n\u003cp id=\"system_architecture\"\u003e\n\n## 2. System Architecture\n\nOur software is written in C, C++ and Python. Voice recording and processing is done\nin Python. Everything related to the OLED display is done in C and C++.\n\nAfter successfully processing the voice data, the text is transferred through sockets\nto the C program. The C program then executes the incoming command in a separate\nprocess and it's result is transferred to the main program via pipes. When the command\nand it's result is obtained, they are both printed to the OLED screen on the current\ncursor position.\n\n- For button control we used [RPi.GPIO](https://pypi.org/project/RPi.GPIO/).\n- For voice control and processing we used [PyAudio](https://pypi.org/project/PyAudio/).\n- To control the OLED display we used [SSD1306_OLED_RPI](https://github.com/gavinlyonsrepo/SSD1306_OLED_RPI)\n  and [bcm2835](https://www.airspayce.com/mikem/bcm2835/).\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"screenshot/diagram.png\" alt=\"diagram\" width=512px\u003e\u003c/p\u003e\n\n### Voice Processing Program\n\nOur program starts execution by obtaining the IP address that matches its own `hostname`\nand connects to it.\nThen enters an infinite loop. During the loop, it expects user input is\ngiven from the keyboard to record the sound for 5 seconds.\n\nData recording is completed by using\n`data = sd.rec(samplerate * duration, samplerate=samplerate, channels=1, blocking=True).`\nThe sound obtained is then brought to a suitable range with\n`data= ( data * abs_max + abs_max).clip(0,abs_max).astype(np.int16)`\nbefore being written to the disk.\nThen, the voice is read from the file and sent to the Google TTS API.\nThe final message obtained\nafter passing through the `text_processor(text:str)` function is based on the\nresponse from the API. This function converts the incoming message into a command\nformat that can be executed. If the words are found in the pre-defined command\ndictionary, they are replaced.\nIf the final message obtained after the text_processor function is not null,\nit is sent to the C program on the other side via TCP message.\n\n### Display and Execution Program\n\nOur program is written as a multi-process so that the OLED screen can continue\nto process messages while the program is running.\nThe first process is responsible for controlling the OLED screen and running\nthe programs, while the second process acts as the TCP server.\nSince our program runs in two different processes, a pipe structure is used\nfor communication between the two programs. The TCP server takes the writing\nend of the pipe, while the display program takes the reading end.\n\n- #### Display Process\n\n  This process first needs to make various settings.\n  The function `int disp_setup(pid_t p)` is run to set up the OLED display.\n  This function introduces the OLED screen to the program and creates an\n  `SSD1306` object based on the _disp_width_ and _disp_height_ values given.\n  This class contains functions related to the display.\n  After that, the function `void disp_loop(int read_pipe)` is executed.\n  This function prints a text on the screen and starts to listening the\n  reading end of the pipe. The following actions are taken as long as\n  a message other than \"exit\" is received:\n\n  - If the message is \"clear\", the OLED screen is cleared.\n  - If not, the display cursor is placed at the y_index * 8 % 64 position\n    it should be. It then calls the function\n    `char *proc_exec(char *const program, int len)`defined in `proc_util`.\n\n    \"proc_exec\" first calls the function\n    `char **proc_split(const char *const string, int len, int *argc)` defined\n    in the same header. This function parses the given string into a program\n    and arguments.\n\n  - After the parsing is complete, `proc_exec` creates a new process and executes\n    the program and argument data of the process. It redirects `stdout` and `stderr`\n    channels to the write end of the pipe. This allows the output of the\n    created process to be stored in a string.\n  - `disp_loop` writes the program name and result obtained to the OLED buffer\n    and updates the screen. If the screen overflows as a result, the screen is cleared.\n  - If the message is \"exit\", the OLED screen and TCP server processes are\n    terminated instead of the shell's exit command. OLED and TCP are terminated by\n    calling the function `void OLED_exit()` defined in the same header.\n  - If none of these conditions are met, the message is simply written to the OLED\n    screen.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"screenshot/program2.png\" width=\"512px\"\u003e\u003c/p\u003e\n\n- #### TCP Server Process\n\n  This process runs `void serv_loop(int write_pipe)` function. This function creates\n  a socket and listens on port 8081. When a connection is received, it reads\n  the incoming message and writes it to the write end of the pipe. If the received\n  message is \"exit\", the function terminates the server and closes the socket.\n\n\u003cp id=\"hardware\"\u003e\n\n### 3. Hardware Requirements\n\nWe developed our project using Raspberry Pi Zero.\nThe OLED screen and Raspberry's 4th pin are connected to each other.\nThe 1st, 3rd, 5th, and 6th pins of the Raspberry Pi are used.\n3.3V is obtained from the 1st pin. Data flow is provided for communication to occur\nvia the 3rd pin. A common clock is used to ensure proper serial communication via\nthe 5th pin.\nFinally, the OLED's ground pin is connected to the Raspberry Pi's ground pin,\nwhich is the 6th pin.\n\n\u003cp id=\"installation\"\u003e\n\n### 4. Installation\n\n1. Clone the repo\n\n```sh\n   git clone https://github.com/umutsevdi/unix-assistant.git\n```\n\n2. Download the dependencies to the Raspberry Pi.\n\n   - C Dependencies:\n\n     - [bcm2835](https://www.airspayce.com/mikem/bcm2835/)\n     - [SSD1306_OLED_RPI](https://github.com/gavinlyonsrepo/SSD1306_OLED_RPI)\n\n   - Python Dependencies:\n\n     - numpy\n     - SciPy\n     - sounddevice\n     - SpeechRecognition\n     - PyAudio\n\n   - Additional Dependencies:\n\n```sh\nsudo apt install portaudio19-dev python3-pyaudio\n```\n\n3. Compile the C++ program.\n\n```sh\n    cd app/\n    make all\n```\n\n4. Run the C++ program under root privileges.\n\n```sh\n    sudo bin/test\n```\n\n4. Run the Python program.\n\n```sh\n    python main.py\n```\n\n## 5. License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n\u003cp id=\"contact\"\u003e\n\n## 6. Contact\n\nYou can contact any developer of this project for any suggestion or information.\n\nProject: [umutsevdi/unix-assistant](https://github.com/umutsevdi/unix-assistant)\n\n\u003ci\u003eDeveloped by \u003ca href=\"https://github.com/umutsevdi\"\u003e Umut Sevdi\u003c/a\u003e,\n\u003ca href=\"https://github.com/Selimshady\"\u003eYavuz Selim Cagan\u003c/a\u003e,\n\u003ca href=\"https://github.com/semihyazici\"\u003eSemih Yazici\u003c/a\u003e and\n\u003ca href=\"https://github.com/Oguzhanercan\"\u003eOguzhan Ercan\u003c/a\u003e.\u003c/i\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumutsevdi%2Funix-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumutsevdi%2Funix-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumutsevdi%2Funix-assistant/lists"}