*rpi.txt*                         Vim integration for emulated Raspberry Pis

                    ,dkOOKXXOOOdc.   'lxOOKXXKOko,
                    cXMWNXXNWMWOO;  ;KMMWNXXNWMNcl
                    .xWMMNXOOOOKXc  cKKOOOOXNMMWk'
                     ..XWMMMNOc'     .:kNMMMMNx'
                       'cxOOxc.  ... .:xOOOk.,
                       .,cdl..:dOOOOOOkl'.dc'
                      :ONNO:.:KMMMMMMWk,:OONNk;
                     ;OOXx:oo',:loddoool;',cxXO,
                     .;..ckKNXOO..  .cOONNKx:,;.
                   '.c..xWMMMMMWd. ;KMMMMMMMX:.cd,
                  ;KMO':XMMMMMMWd. ,OOMMMMMMMx;OMK:
                  oWMk.'OWMMMMNd.   ;ONMMMMXc.xWxWo
                  ;KK:  ocdxdolodxxdolclooc'  :OOO,
                   .,;cc'.  .cKWMMMMMWk'  .;dxkxd:.
                    .OMMNk; .OMMMMMMMMW. ;OWMMMMX:
                    .xWMMMXl lXMMMMMMWOO cXMMMMK;         _
                     .dXWMMO. 'lxkkkdc .kMMMWO;    _   __( )___ ___
                       'coo;oo,:loool:'o;ool;o    | | / / / __ `__ \
                            olXWMMMMMMMNko      _ | |/ / / / / / / /
                                               (.)|___/_/_/ /_/ /_/

Maintainer: Robert Di Pardo <[email protected]>
License:    https://github.com/rdipardo/rpi-vim/blob/main/LICENSE

==============================================================================
CONTENTS                                                 *rpi-contents*

    Requirements ................................... |rpi-requirements|
    Installation ................................... |rpi-installation|
      * Manual ................................ |rpi-vim8-pack-install|
      * Via Plugin Manager ...................... |rpi-managed-install|
    Configuration ......................................... |rpi-setup|
      * Options .................................. |rpi-config-options|
      * Compiler Flags ............................ |rpi-config-cflags|
    Commands ........................................... |rpi-commands|
    References  ............................................ |rpi-refs|
    Acknowledgements ................................... |rpi-3rdparty|

==============================================================================
REQUIREMENTS                                              *rpi-requirements*

* rsync

To mount an RPi image from inside Vim, you will also need:

* the Docker CLI: https://docs.docker.com/engine/install
* curl
* unzip
* xz-utils (DEB distros)
* xz       (RPM distros)

==============================================================================
INSTALLATION                                              *rpi-installation*

Manual                                               *rpi-vim8-pack-install*
~~~~~~

Using Vim 8 or newer, copy the plugin source tree into Vim's |packages| path,
for example:

  $ mkdir -p ~/.vim/pack/plugins/start
  $ git clone https://github.com/rdipardo/rpi-vim.git ~/.vim/pack/plugins/start/rpi-vim


Via Plugin Manager                                     *rpi-managed-install*
~~~~~~~~~~~~~~~~~~

Using |vim-plug|:

  $ curl -sfLo  ~/.vim/autoload/plug.vim --create-dirs \
      https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

Edit your '.vimrc' by adding:
>
    call plug#begin('~/path/to/your/plugin/directory/')
    " ...
    Plug 'rdipardo/rpi-vim'
    " ...
    call plug#end()
<

Start Vim and run the |:PlugInstall| command.

Using |Vundle.vim|:

  $ git clone https://github.com/VundleVim/Vundle.vim.git ~/.vim/bundle/Vundle.vim

Edit your '.vimrc' by adding:
>
    set rtp+=~/.vim/bundle/Vundle.vim
    call vundle#begin()
    " ...
    Plugin 'rdipardo/rpi-vim'
    " ...
    call vundle#end()
<

Start Vim and run the |:VundleInstall!| command.

==============================================================================
CONFIGURATION                                                    *rpi-setup*

Source files are copied to the RPi over a secure shell and compiled with the
native GCC toolchain. If the SSH server is not already enabled on the RPi, log
in and run:

    $ sudo raspi-config

Select 'Interface Options' > 'Configure connections to peripherals', then
'SSH' > 'Enable/disable remote command line access using SSH'.

When prompted, select 'Yes' > 'Ok' > 'Finish'.

Open a fresh terminal on the host OS and try the connection:

    $ ssh -T |SSH_HOST| -p |SSH_PORT| "uname -a"

Start vim and run the |:RPiSetup| command. Enter the RPi user password when
prompted.

NOTE
The default 'pi' user was removed in the 2022-04-04 Bullseye release.
See https://downloads.raspberrypi.org/raspios_lite_armhf/release_notes.txt

Options                                                 *rpi-config-options*
~~~~~~~

To configure the virtual machine's startup parameters, create a '.env' file in
the root of your project's source directory.

                                                                *OS_VERSION*
  Raspberry Pi OS version string
  Default: '2022-01-28-raspios-bullseye-arm64-lite'

                                                              *OS_IMAGE_URL*
  URL where |OS_VERSION| is hosted
  Default: 'https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-01-28'

                                                                 *RPI_BOARD*
  Model number of the board to virtualize
  Default: 'pi3'

  NOTE
  Valid options are: 'pi1', 'pi2', 'pi3' or '' (empty).
  If the model number is empty, and |OS_VERSION| targets `armhf`, the image is
  mounted to a virtual ARM Versatile board by default.

  See:
>
    https://github.com/lukechilds/dockerpi#which-machines-are-supported
    https://www.qemu.org/docs/master/system/arm/versatile.html
<

                                                                  *SSH_HOST*
  User and host name of the RPi's SSH server
  Default: 'pi@localhost'

                                                                  *SSH_PORT*
  Port number the RPi's SSH server is listening on
  Default: 5022
                                                              *SSH_PASSWORD*
  Login password for |SSH_HOST|
  Default: ''

                                                                *SSH_PARAMS*
  Additional options for the ssh client
  Default: ''

                                                                  *WORK_DIR*
  Directory on the RPi where source files will be copied
  Default: '~'

For example:
>
  OS_VERSION='2022-04-04-raspios-buster-armhf-lite'
  OS_IMAGE_URL='https://downloads.raspberrypi.org/raspios_oldstable_lite_armhf/images/raspios_oldstable_lite_armhf-2022-04-07'
  SSH_PARAMS='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'
  WORK_DIR='~/assembly-source'
<

Compiler Flags                                           *rpi-config-cflags*
~~~~~~~~~~~~~~

Create a '.cflags' file in the root of your project's source directory.
Any *CFLAGS* , *CXXFLAGS* or *LDFLAGS* variable defined here will be passed to
the VM's compiler.

For example:
>
  CFLAGS='-I/opt/vc/include -std=c11'
  CXXFLAGS='-std=gnu++2b'
  LDFLAGS='-L/opt/vc/lib -lbcm_host'
<
==============================================================================
COMMANDS                                                      *rpi-commands*

                                                               *:RPiCompile*
        :RPiCompile
        Default mapping: {Normal}<F8>

Copy the active buffer to the RPi VM and compile it.

                                                                  *:RPiMake*
        :RPiMake [{target}]
        Default mapping: {Normal}<F9>

If the working directory contains a Makefile, copy all source files to the RPi
VM and run `make` with the given {target}, if any.

If no Makefile exits, copy, compile and link all source files using the
|CFLAGS|, |CXXFLAGS| and |LDFLAGS| variables in the user's '.cflags' file.

                                                                   *:RPiRun*
        :RPiRun
        Default mapping: {Normal}<F7>

Execute the active buffer on the RPi VM.

                                                                 *:RPiSetup*
        :RPiSetup  [{key_file_path}] [{key_file_password}]

Create a new SSH key file at {key_file_path} with {key_file_password} and copy
it to the RPi VM at |SSH_HOST|. Also copy the plugin's required build scripts
after a successful connection is made. All parameters are optional.

                                                                  *:RPiBoot*
        :RPiBoot  [{image_file_directory}]

Search {image_file_directory} for an RPi OS image file matching |OS_VERSION|
and mount it inside a Docker container.

If no {image_file_directory} is given, search the plugin's installation path.
If no image matching |OS_VERSION| is found, try downloading it from |OS_IMAGE_URL|.

==============================================================================
REFERENCES                                                        *rpi-refs*

                                                                *Vundle.vim*
  https://github.com/VundleVim/Vundle.vim#quick-start

                                                                  *vim-plug*
  https://github.com/junegunn/vim-plug#installation

==============================================================================
ACKNOWLEDGEMENTS                                              *rpi-3rdparty*

This plugin uses the lukechilds/dockerpi Docker image to mount RPi OS images.

lukechilds/dockerpi (c) 2017 Luke Childs, MIT License, https://github.com/lukechilds/dockerpi

=============================================================================
vim:tw=78:noet:ft=help:norl: