Skip to content

Commit c1cc3e3

Browse files
stevearcstevearc
committed
doc: rework the README
1 parent fb1991e commit c1cc3e3

File tree

1 file changed

+142
-50
lines changed

1 file changed

+142
-50
lines changed

‎README.md

Lines changed: 142 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,155 @@
11
# vim-arduino
2+
23
Vim plugin for compiling, uploading, and debugging arduino sketches. It uses
3-
[arduino-cli](https://arduino.github.io/arduino-cli/latest/) when available, and
4-
falls back to using the Arduino IDE's [commandline
4+
[arduino-cli](https://arduino.github.io/arduino-cli/latest/) when available
5+
(recommended), and falls back to using the Arduino IDE's [commandline
56
interface](https://github.com/arduino/Arduino/blob/master/build/shared/manpage.adoc)
67
(new in 1.5.x).
78

89
## Installation
910

10-
vim-arduino works with [Pathogen](https://github.com/tpope/vim-pathogen)
11+
vim-arduino works with all the usual plugin managers
12+
13+
<details>
14+
<summary>Packer (Neovim only)</summary>
15+
16+
```lua
17+
require('packer').startup(function()
18+
use {'stevearc/vim-arduino'}
19+
end)
20+
```
21+
22+
</details>
23+
24+
<details>
25+
<summary>Paq (Neovim only)</summary>
26+
27+
```lua
28+
require "paq" {
29+
{'stevearc/vim-arduino'};
30+
}
31+
```
32+
33+
</details>
34+
35+
<details>
36+
<summary>vim-plug</summary>
37+
38+
```vim
39+
Plug 'stevearc/vim-arduino'
40+
```
41+
42+
</details>
43+
44+
<details>
45+
<summary>dein</summary>
46+
47+
```vim
48+
call dein#add('stevearc/vim-arduino')
49+
```
50+
51+
</details>
52+
53+
<details>
54+
<summary>Pathogen</summary>
1155

1256
```sh
13-
cd ~/.vim/bundle/
14-
git clone https://github.com/stevearc/vim-arduino
57+
git clone --depth=1 https://github.com/stevearc/vim-arduino.git ~/.vim/bundle/
1558
```
1659

17-
and [vim-plug](https://github.com/junegunn/vim-plug)
60+
</details>
61+
62+
<details>
63+
<summary>Neovim native package</summary>
1864

1965
```sh
20-
Plug 'stevearc/vim-arduino'
66+
git clone --depth=1 https://github.com/stevearc/vim-arduino.git \
67+
"${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/vim-arduino/start/vim-arduino
2168
```
2269

23-
Installation instructions for `arduino-cli` are here: https://arduino.github.io/arduino-cli/latest/installation/
70+
</details>
2471

25-
Otherwise (or in addition to), download [Arduino
26-
IDE](https://www.arduino.cc/en/Main/Software) (version 1.5 or newer). Linux
27-
users make sure the `arduino` command is in your PATH.
72+
<details>
73+
<summary>Vim8 native package</summary>
2874

29-
## Platforms
75+
```sh
76+
git clone --depth=1 https://github.com/stevearc/vim-arduino.git \
77+
"$HOME"/.vim/pack/vim-arduino/start/vim-arduino
78+
```
3079

31-
vim-arduino should work with no special configuration on Linux and Mac. I have
32-
not tested on Windows, but have heard that it works via WSL. See
33-
[this issue](https://github.com/stevearc/vim-arduino/issues/4) for discussion.
80+
</details>
3481

35-
## Configuration
82+
## Requirements
3683

37-
The docs have detailed information about configuring vim-arduino
38-
[here](https://github.com/stevearc/vim-arduino/blob/master/doc/arduino.txt).
84+
Linux and Mac are tested and functioning. I have not tested on Windows, but have
85+
heard that it works via WSL. See [this
86+
issue](https://github.com/stevearc/vim-arduino/issues/4) for discussion.
87+
88+
It is recommended to use `arduino-cli`, installation instructions here: https://arduino.github.io/arduino-cli/latest/installation/
89+
90+
However it is also possible to use the arduino IDE directly. Download [Arduino
91+
IDE](https://www.arduino.cc/en/Main/Software) (version 1.5 or newer). Linux
92+
users make sure the `arduino` command is in your PATH.
3993

40-
The main commands you will want to use are:
94+
## Commands
4195

42-
* `:ArduinoChooseBoard` - Select the type of board from a list.
43-
* `:ArduinoChooseProgrammer` - Select the programmer from a list.
44-
* `:ArduinoChoosePort` - Select the serial port from a list.
45-
* `:ArduinoVerify` - Build the sketch.
46-
* `:ArduinoUpload` - Build and upload the sketch.
47-
* `:ArduinoSerial` - Connect to the board for debugging over a serial port.
48-
* `:ArduinoUploadAndSerial` - Build, upload, and connect for debugging.
49-
* `:ArduinoInfo` - Display internal information. Useful for debugging issues with vim-arduino.
96+
| Command | arg | description |
97+
| ------------------------- | ------------ | --------------------------------------------------------------------------- |
98+
| `ArduinoChooseBoard` | [board] | Select the type of board. With no arg, will present a choice dialog. |
99+
| `ArduinoChooseProgrammer` | [programmer] | Select the programmer. With no arg, will present a choice dialog. |
100+
| `ArduinoChoosePort` | [port] | Select the serial port. With no arg, will present a choice dialog. |
101+
| `ArduinoVerify` | | Build the sketch. |
102+
| `ArduinoUpload` | | Build and upload the sketch. |
103+
| `ArduinoSerial` | | Connect to the board for debugging over a serial port. |
104+
| `ArduinoUploadAndSerial` | | Build, upload, and connect for debugging. |
105+
| `ArduinoInfo` | | Display internal information. Useful for debugging issues with vim-arduino. |
50106

51107
To make easy use of these, you may want to bind them to a key combination. You
52-
can put the following in `.vim/ftplugin/arduino.vim`:
108+
can put them in `ftplugin/arduino.vim`:
53109

54110
```vim
55-
nnoremap <buffer> <leader>am :ArduinoVerify<CR>
56-
nnoremap <buffer> <leader>au :ArduinoUpload<CR>
57-
nnoremap <buffer> <leader>ad :ArduinoUploadAndSerial<CR>
58-
nnoremap <buffer> <leader>ab :ArduinoChooseBoard<CR>
59-
nnoremap <buffer> <leader>ap :ArduinoChooseProgrammer<CR>
111+
" Change these as desired
112+
nnoremap <buffer> <leader>am <cmd>ArduinoVerify<CR>
113+
nnoremap <buffer> <leader>au <cmd>ArduinoUpload<CR>
114+
nnoremap <buffer> <leader>ad <cmd>ArduinoUploadAndSerial<CR>
115+
nnoremap <buffer> <leader>ab <cmd>ArduinoChooseBoard<CR>
116+
nnoremap <buffer> <leader>ap <cmd>ArduinoChooseProgrammer<CR>
60117
```
61118

62-
If you wish to run these commands in tmux/screen/some other location, you can
63-
make use of [vim-slime](https://github.com/jpalardy/vim-slime):
119+
## Configuration
64120

65-
```vim
66-
let g:arduino_use_slime = 1
67-
```
121+
By default you should not _need_ to set any options for vim-arduino to work
122+
(especially if you're using `arduino-cli`, which tends to behave better). If
123+
you want to see what's available for customization, there is detailed
124+
information [in the vim docs](https://github.com/stevearc/vim-arduino/blob/master/doc/arduino.txt).
125+
126+
## Integrations
127+
128+
### Dialog / picker plugins
129+
130+
The built-in mechanism for choosing items (e.g. `:ArduinoChooseBoard`) uses
131+
`inputlist()` and is not very pretty or ergonomic. If you would like to improve
132+
the UI, there are two approaches:
133+
134+
- **Neovim:** override `vim.ui.select` (e.g. by using a plugin like [dressing.nvim](https://github.com/stevearc/dressing.nvim))
135+
- **Vim8:** install [ctrlp](https://github.com/ctrlpvim/ctrlp.vim) or [fzf](https://github.com/junegunn/fzf.vim). They will automatically be detected and used
136+
137+
### Tmux / screen
138+
139+
If you want to run the arduino commands in a separate tmux or screen pane, use
140+
[vim-slime](https://github.com/jpalardy/vim-slime). By setting `let g:arduino_use_slime = 1` vim-arduino will send the commands via `slime#send()` instead of running them inside a vim terminal.
68141

69142
### Status Line
70143

71-
If you want to add the board type to your status line, it's easy with the
72-
following:
144+
You may want to display the arduino state in your status line. There are four
145+
pieces of data you may find interesting:
73146

74-
```vim
75-
" my_file.ino [arduino:avr:uno]
76-
function! MyStatusLine()
77-
return '%f [' . g:arduino_board . ']'
78-
endfunction
79-
setl statusline=%!MyStatusLine()
80-
```
147+
- **g:arduino_board** - the currently selected board
148+
- **g:arduino_programmer** - the currently selected programmer
149+
- **g:arduino_serial_baud** - the baud rate that will be used for Serial commands
150+
- **arduino#GetPort()** - returns the port that will be used for communication
81151

82-
This is my personal configuration (again, inside `ftplugin/arduino.vim`)
152+
An example with vanilla vim or nvim, added to `ftplugin/arduino.vim`:
83153

84154
```vim
85155
" my_file.ino [arduino:avr:uno] [arduino:usbtinyisp] (/dev/ttyACM0:9600)
@@ -96,14 +166,36 @@ augroup ArduinoStatusLine
96166
autocmd BufWinEnter <buffer> setlocal stl=%f\ %h%w%m%r\ %{ArduinoStatusLine()}\ %=\ %(%l,%c%V\ %=\ %P%)
97167
augroup END
98168
```
99-
Note: if you are using the 'airline' plugin for the status line, you can display
100-
this custom status part instead of the filename extension with:
169+
170+
To do the same thing with [vim-airline](https://github.com/vim-airline/vim-airline):
101171

102172
```vim
103173
autocmd BufNewFile,BufRead *.ino let g:airline_section_x='%{MyStatusLine()}'
104174
```
105175

176+
For [lualine](https://github.com/nvim-lualine/lualine.nvim) (Neovim only) I use
177+
the following function:
178+
179+
```lua
180+
local function arduino_status()
181+
local ft = vim.api.nvim_buf_get_option(0, "ft")
182+
if ft ~= "arduino" then
183+
return ""
184+
end
185+
local port = vim.fn["arduino#GetPort"]()
186+
local line = string.format("[%s]", vim.g.arduino_board)
187+
if vim.g.arduino_programmer ~= "" then
188+
line = line .. string.format(" [%s]", vim.g.arduino_programmer)
189+
end
190+
if port ~= 0 then
191+
line = line .. string.format(" (%s:%s)", port, vim.g.arduino_serial_baud)
192+
end
193+
return line
194+
end
195+
```
196+
106197
## License
198+
107199
Everything is under the [MIT
108200
License](https://github.com/stevearc/vim-arduino/blob/master/LICENSE) except for
109201
the wonderful syntax file, which was created by Johannes Hoff and copied from

0 commit comments

Comments
 (0)