{"id":13631995,"url":"https://github.com/hypriot/flash","last_synced_at":"2025-05-15T18:06:16.709Z","repository":{"id":29332379,"uuid":"32866104","full_name":"hypriot/flash","owner":"hypriot","description":"Command line script to flash SD card images of any kind","archived":false,"fork":false,"pushed_at":"2022-06-06T09:48:11.000Z","size":269,"stargazers_count":1014,"open_issues_count":28,"forks_count":173,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-03T04:12:55.253Z","etag":null,"topics":["card-reader","flash","hypriot-flash","hypriot-os","raspberry-pi","sd-card-image","sd-cards","wifi-settings"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/hypriot.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":"2015-03-25T13:25:54.000Z","updated_at":"2025-04-01T08:51:49.000Z","dependencies_parsed_at":"2022-08-24T02:50:44.999Z","dependency_job_id":null,"html_url":"https://github.com/hypriot/flash","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypriot%2Fflash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypriot%2Fflash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypriot%2Fflash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypriot%2Fflash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypriot","download_url":"https://codeload.github.com/hypriot/flash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248170643,"owners_count":21059228,"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":["card-reader","flash","hypriot-flash","hypriot-os","raspberry-pi","sd-card-image","sd-cards","wifi-settings"],"created_at":"2024-08-01T22:02:47.503Z","updated_at":"2025-04-10T06:36:26.955Z","avatar_url":"https://github.com/hypriot.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# flash\n\n[![CircleCI](https://circleci.com/gh/hypriot/flash.svg?style=svg)](https://circleci.com/gh/hypriot/flash)\n[![Build Status](https://travis-ci.org/hypriot/flash.svg?branch=master)](https://travis-ci.org/hypriot/flash)\n[![Release](https://img.shields.io/github/release/hypriot/flash.svg)](https://github.com/hypriot/flash/releases)\n[![Stars](\thttps://img.shields.io/github/stars/hypriot/flash.svg?style=social\u0026label=Stars)](https://github.com/hypriot/flash#installation)\n\nCommand line script to flash SD card images of any kind.\n\nNote that for some devices (e.g. Raspberry Pi), at the end of the flashing process the tool tries to customize the SD card e.g. it configures a hostname or WiFi. And with a cloud-init enabled image you can do much more like adding users, SSH keys etc.\n\nThe typical workflow looks like this:\n\n[![asciicast](https://asciinema.org/a/4k72pounxxybtix84ecl4b69w.png)](https://asciinema.org/a/4k72pounxxybtix84ecl4b69w)\n\n1. Run `flash https://github.com/hypriot/image-builder-rpi/releases/download/v1.12.0/hypriotos-rpi-v1.12.0.img.zip`\n2. Insert SD card to your notebook\n3. Press RETURN\n4. Eject SD card and insert it to your Raspberry Pi - done!\n\nThis script can\n\n* download a compressed SD card from the internet or from S3\n* use a local SD card image, either compressed or uncompressed\n* wait until a SD card is plugged in\n* search for a SD card plugged into your Computer\n* show progress bar while flashing (if `pv` is installed)\n* copy an optional cloud-init `user-data` and `meta-data` file into the boot partition of the SD image\n* copy an optional `config.txt` file into the boot partition of the SD image (eg. to enable onboard WiFi)\n* copy an optional `device-init.yaml` or `occidentalis.txt` file into the boot partition of the SD image (for older HypriotOS versions)\n* copy an optional custom file into the boot partition of the SD image\n* optional set the hostname of this SD image\n* optional set the WiFi settings as well\n* play a little sound after flashing\n* unplugs the SD card\n\nAt the moment only Mac OS X and Linux is supported.\n\n## Installation\n\nDownload the appropriate version for Linux or Mac with this command\n\n```bash\ncurl -LO https://github.com/hypriot/flash/releases/download/2.7.2/flash\nchmod +x flash\nsudo mv flash /usr/local/bin/flash\n```\n\n### Install Dependencies\n\nThe `flash` script needs optional tools\n\n* `curl` - if you want to flash directly with an HTTP URL\n* `aws` - if you want to flash directly from an AWS S3 bucket\n* `pv` - to see a progress bar while flashing with the `dd` command\n* `unzip` - to extract zip files.\n* `hdparm` - to run the program\n\n#### Mac\n\n```bash\nbrew install pv\nbrew install awscli\n```\n\n#### Linux (Debian/Ubuntu)\n\n```bash\nsudo apt-get install -y pv curl python-pip unzip hdparm\nsudo pip install awscli\n```\n\n## Usage\n\n```bash\n$ flash --help\nusage: flash [options] [name-of-rpi.img]\n\nFlash a local or remote Raspberry Pi SD card image.\n\nOPTIONS:\n   --help|-h      Show this message\n   --bootconf|-C  Copy this config file to /boot/config.txt\n   --config|-c    Copy this config file to /boot/device-init.yaml (or occidentalis.txt)\n   --hostname|-n  Set hostname for this SD image\n   --ssid|-s      Set WiFi SSID for this SD image\n   --password|-p  Set WiFI password for this SD image\n   --clusterlab|-l Start Cluster-Lab on boot: true or false\n   --device|-d    Card device to flash to (e.g. /dev/disk2)\n   --force|-f     Force flash without security prompt (for automation)\n   --userdata|-u  Copy this cloud-init config file to /boot/user-data\n   --metadata|-m  Copy this cloud-init config file to /boot/meta-data\n   --file|-F      Copy this custom file to /boot\n```\n\n## Configuration\n\nThe strength of the flash tool is that it can insert some configuration files that gives you the best first boot experience to customize the hostname, WiFi and even user logins and SSH keys automatically.\n\n### cloud-init\n\nWith HypriotOS v1.7.0 and higher the options `--userdata` and `--metadata` can be used to copy both cloud-init config files into the FAT partition.\n\nThis is an example how to create our default user with a password.\n\n```yaml\n#cloud-config\n# vim: syntax=yaml\n#\nhostname: black-pearl\nmanage_etc_hosts: true\n\nusers:\n  - name: pirate\n    gecos: \"Hypriot Pirate\"\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    shell: /bin/bash\n    groups: users,docker,video\n    plain_text_passwd: hypriot\n    lock_passwd: false\n    ssh_pwauth: true\n    chpasswd: { expire: false }\n\npackage_upgrade: false\n```\n\nPlease have a look at the [`sample`](sample/) folder, our guest blogpost [Bootstrapping a Cloud with Cloud-Init and HypriotOS](https://blog.hypriot.com/post/cloud-init-cloud-on-hypriot-x64/) or at the [cloud-init documentation](http://cloudinit.readthedocs.io/en/0.7.9/)\nhow to do more things like using SSH keys, running additional commands etc.\n\n### config.txt\n\nThe option `--bootconf` can be used to copy a `config.txt` into the SD image\nbefore it is unplugged.\n\nWith this option it is possible to change some memory, camera, video settings\netc. See the [config.txt documentation](https://www.raspberrypi.org/documentation/configuration/config-txt/README.md)\nat raspberrypi.org for more details.\n\nThe boot config file config.txt has name/value pairs such as:\n\n```bash\nmax_usb_current=1\nhdmi_force_hotplug=1\n```\n\n### device-init.yaml\n\nFor HypriotOS older than v1.7.0 the option `--config` can be used to copy a\n`device-init.yaml` into the SD image before it is unplugged. This YAML file can\nbe read by newer HyperiotOS SD images.\n\nThe config file device-init.yaml should look like\n\n```yaml\nhostname: black-pearl\nwifi:\n  interfaces:\n    wlan0:\n      ssid: \"MyNetwork\"\n      password: \"secret_password\"\n```\n\nIf you don't want to set any wifi settings, comment out or remove the wlan0, ssid and password.\n\n## fake-hwclock.data\n\nHypriotOS 1.12.0 and higher has the `/etc/fake-hwclock.data` file symlinked to the boot partition. Flash tool updates this timestamp with the current time (UTC timezone). This fixes problems running commands that communicate with the internet with a wrong initial date on first boot.\n\n## Use cases\n\n### Flash a compressed SD image from the internet\n\n```bash\nflash https://github.com/hypriot/image-builder-rpi/releases/download/v1.12.0/hypriotos-rpi-v1.12.0.img.zip\n```\n\n### Flash and change the hostname\n\nThis works only for SD card images that already have `occi` installed.\n\n```bash\nflash --hostname mypi hypriot.img\n```\n\nThen unplug the SD card from your computer, plug it into your Pi and boot your\nPi. After a while the Pi can be found via Bonjour/avahi and you can log in with\n\n```bash\nssh pi@mypi.local\n```\n\n### Onboard WiFi\n\nThe options `--userdata` and `--bootconf` must be used to disable UART and enable onboard WiFi for Raspberry Pi 3 and Pi 0. For external WiFi sticks you do not need to specify the `-bootconf` option.\n\n```\nflash --userdata sample/wlan-user-data.yaml --bootconf sample/no-uart-config.txt hypriotos-rpi-v1.12.0.img\n```\n\n### Automating flash\n\nFor non-interactive usage, you can predefine the user input in the flash command with the `-d` and `-f` options:\n\n```\nflash -d /dev/mmcblk0 -f hypriotos-rpi-v1.12.0.img\n```\n\n## Development\n\nPull requests and other feedback is always welcome. The `flash` tool should fit\nour all needs and environments.\n\nTo develop the flash scripts you need either a Linux or macOS machine to test locally. On a Mac you can use Docker to run the Linux tests in a container and if you dare you can run the macOS tests directly. On a Linux machine you can not test the macOS variant directly. But in every case you can send a pull request and push code to GitHub and the CI pipeline with CircleCI (Linux) and TravisCI (macOS) will test your code for both platforms.\n\n### Local development\n\nThe flash script are checked with the [`shellcheck`](https://www.shellcheck.net) static analysis tool.\n\nThe integration tests can be run locally on macOS or Linux. We use BATS which is installed with NPM package. So you would need Node.js to setup a local development environment. As the flash script runs `dd` and some commands with `sudo` it is recommended to use the isolated test environment with Docker or run this local tests in a macOS / Linux VM.\n\n```\nnpm install\nnpm test\n```\n\n### Isolated tests with Docker\n\nIf you do not want to install all these development tools (shellcheck, bats, node) and don't trust the flash script enough, you can use Docker instead and run the shellcheck and integration tests in a much safer test environment.\n\nAll you need is Docker and `make` installed to run the following tests.\n\n#### Shellcheck\n\nThe flash script are checked with the shellcheck static analysis tool.\n\n```\nmake shellcheck\n```\n\n#### Integration tests\n\nThe flash script also have BATS integration tests. You don't have to install everything on your development machine. It should be enough to test the Linux variant in a Docker container and then run the macOS tests with TravisCI.\n\n```\nmake test\n```\n\n### Test Linux from Mac\n\nFor manual tests of the Linux version on a Mac there is a Vagrant environment. It can be used\nto investigate Linux problems when you don't have a baremetal Linux machine. With some help I found a way to spin up a\nVirtualBox Vagrant box with Ubuntu that maps the internal Apple SD card reader\ninto the VM. Thanks to [Flexshot](https://github.com/Flexshot) for the helper\nfunctions I found in [NextThingCo/CHIP-SDK#15](https://github.com/NextThingCo/CHIP-SDK/pull/15).\n\nCheck the vendor ID and product ID in \"About this Mac\" -\u003e System Report ... -\u003e\nCard Reader. I found the vendor ID 0x05ac and product ID 0x8406 can be found in\nthe `Vagrantfile`.\n\n```bash\nvagrant up --provider virtualbox\nvagrant ssh\ncd /vagrant\n./flash hypriotos-rpi-v1.12.0.img.zip\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypriot%2Fflash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypriot%2Fflash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypriot%2Fflash/lists"}