Split up Readme and move explanations to a docs folder. (#149)
* Split up Readme and move explanations to a docs folder. Signed-off-by: Jerome Luckenbach <github@luckenba.ch> * Add some links. Signed-off-by: Jerome Luckenbach <github@luckenba.ch>pull/154/head
Jerome Luckenbach
GitHub
parent
89ff23f564
commit
736e4b7492
139
README.md
139
README.md
|
|
@ -1,6 +1,11 @@
|
|||
# openHAB VS Code Extension
|
||||
|
||||
[](https://openhab.visualstudio.com/vscode-openhab/_build/latest?definitionId=2&branchName=master)
|
||||
](https://img.shields.io/azure-devops/build/openhab/82e39b03-2e63-4a34-84ca-3cb57be32202/2/master?logo=azure-pipelines&logoColor=blue)
|
||||
](https://img.shields.io/azure-devops/tests/openhab/82e39b03-2e63-4a34-84ca-3cb57be32202/2/master?logo=azure-devops&logoColor=blue)
|
||||
[](https://opensource.org/licenses/EPL-2.0)
|
||||
](https://img.shields.io/visual-studio-marketplace/stars/openhab.openhab?color=orange&label=marketplace&logo=visual-studio-code&logoColor=blue)
|
||||
](https://img.shields.io/visual-studio-marketplace/d/openhab.openhab?logo=visual-studio-code&logoColor=blue)
|
||||
|
||||
|
||||
[openHAB](http://www.openhab.org) is a vendor and techology agnostic open source automation software for your home. This [Visual Studio Code](https://code.visualstudio.com) extension allows you to work with openHAB configuration files (like `*.items`, `*.rules`, `*.sitemap` and `*.script`) thanks to the syntax highlighting, code snippets and integrated search.
|
||||
|
||||
|
|
@ -10,7 +15,6 @@ The extension is designed with openHAB 2.x in mind - most snippets and design pa
|
|||
|
||||
* Syntax highlighting for the [openHAB DSL](https://www.openhab.org/docs/configuration/) (rules, items, scripts and sitemaps).
|
||||
* Code snippets for openHAB, including [Design Patterns](https://community.openhab.org/tags/designpattern) by Rich Koshak
|
||||
* Integrated quick search of [openHAB Docs page](http://docs.openhab.org) (`Alt + Shift + O`)
|
||||
* Integrated quick search of [openHAB Community](https://community.openhab.org)
|
||||
* Integrated Basic UI (or Classic UI) browser window (`Ctrl + Alt + O` or editor title icon)
|
||||
* Integrated Paper UI preview for the Items and Things
|
||||
|
|
@ -22,142 +26,21 @@ The extension is designed with openHAB 2.x in mind - most snippets and design pa
|
|||
* Quick Karaf console access
|
||||
* Add Items to Sitemap with one click
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
You are able to configure the hostname and port for the Sitemap preview.
|
||||
|
||||
* openhab.host (mandatory), default: openhabianpi
|
||||
* openhab.port (optional), default: 8080
|
||||
|
||||
*openhab.host* will also work with the IP address of your openHAB instance, instead of the hostname.
|
||||
|
||||
These settings should work fine on Windows machines and openHAB installations using the recommended [openHABian](https://www.openhab.org/docs/installation/openhabian.html) setup.
|
||||
They should be edited if you use macOS or *NIX systems or manual openHAB installations.
|
||||
|
||||
To edit these settings, simply add overrides to either your user settings or your workspace settings in your Visual Studio Codes preferences.
|
||||
|
||||
For further informations on how to change your settings, visit the official [Visual Studio Code docs](https://code.visualstudio.com/docs/getstarted/settings).
|
||||
|
||||
### Configuration example (local)
|
||||
|
||||
```json
|
||||
{
|
||||
"openhab.host": "localhost",
|
||||
"openhab.port": 80
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration example (macOS)
|
||||
|
||||
```json
|
||||
{
|
||||
"openhab.host": "openhabianpi.local",
|
||||
"openhab.port": 8080
|
||||
}
|
||||
```
|
||||
|
||||
### Integration with openHAB REST API
|
||||
|
||||
This VSCode extension connects to the openHAB REST API by default.
|
||||
The connection is used to display list of Items in the left side tree view.
|
||||
It's also utilized for code completions.
|
||||
|
||||
If you're using this extension just for the syntax highlighting
|
||||
and don't want to involve the REST API, you can disable it by providing
|
||||
the following parameter in your User Settings (`Ctrl + Shift + S`):
|
||||
|
||||
```
|
||||
"openhab.useRestApi": false
|
||||
```
|
||||
|
||||
You may need to reload the VSCode window to take effect.
|
||||
|
||||
## Validating the Rules
|
||||
|
||||
This extension comes with Language Server Protocol support.
|
||||
Language servers allow you to add your own validation logic to files open in VS Code.
|
||||
openHAB from version `openHAB 2.2.0 Build #1065` (SNAPSHOT) has the Language Server exposed on `5007` port.
|
||||
openHAB 2.2 since build #1084 has LSP feature enabled in the runtime, so there are no additional steps for you to make it work.
|
||||
|
||||
In the unlikely case that your language server is running on a port other than the default one this is how it can be changed in the configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"openhab.remoteLspPort": 5007
|
||||
}
|
||||
```
|
||||
|
||||
If you don't want to have your openHAB files validated by Language Server, simply disable it in the extension:
|
||||
```json
|
||||
{
|
||||
"openhab.remoteLspEnabled": false
|
||||
}
|
||||
```
|
||||
|
||||
## Accessing remote openHAB
|
||||
|
||||
Accessing remote openHAB from service like myopenhab is not possible, given that you need an access to the file system in order to read and write to the configuration files.
|
||||
Although, you can access the Items and Things through the REST API.
|
||||
Note that LSP (content assist for rules and syntax validation) won't be exposed, so you'll need to disable it too.
|
||||
|
||||
The following configuration will allow you to access REST API remotely:
|
||||
|
||||
```
|
||||
"openhab.host": "https://home.myopenhab.org",
|
||||
"openhab.port": 80,
|
||||
"openhab.remoteLspEnabled": false,
|
||||
"openhab.username": "your_myopenhab_email",
|
||||
"openhab.password": "your_myopenhab_password",
|
||||
```
|
||||
|
||||
## Sitemap preview with Basic UI
|
||||
|
||||
openHAB VS Code Extension allows you to preview the [sitemap structure](https://www.openhab.org/docs/configuration/sitemaps.html) in the [Basic UI](https://www.openhab.org/docs/configuration/ui/basic/) running on your openHAB server instance.
|
||||
|
||||
If you have a sitemap file active in your editor and open Basic UI (`Ctrl + Alt + O` or editor title icon), you'll land directly on the sitemap you're working on.
|
||||
|
||||
You can optionally set `openhab.sitemapPreviewUI` parameter to `classicui` if you prefer Classic UI instead:
|
||||
```json
|
||||
{
|
||||
"openhab.sitemapPreviewUI": "classicui"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
You need to have openHAB server running in order to preview changes. The extension assumes that you access your openHAB config files from either:
|
||||
|
||||
Samba share (e.g. `\\OPENHABIANPI\openHAB-conf\`)
|
||||
Local folder (e.g. `c:\openhab\configuration`)
|
||||
|
||||
## Quick Karaf console access
|
||||
|
||||
|
||||
|
||||
This extension allows you to run openHAB Karaf console directly from the editor.
|
||||
Note that you need to have:
|
||||
|
||||
* `ssh` installed on your environment
|
||||
* Karaf exposed to the external interface
|
||||
* `openhab.host` configuration parameter set properly
|
||||
|
||||
This feature allows you to modify the new param and e.g. show the openHAB logs immediately:
|
||||
|
||||
```
|
||||
"openhab.karafCommand": "ssh openhab@%openhabhost% -p 8101 -t 'log:tail'",
|
||||
```
|
||||
Learn more about the configuration options in our [documentation](https://github.com/openhab/openhab-vscode/blob/master/docs/USAGE.md) on github.
|
||||
|
||||
## Things Explorer demo
|
||||
|
||||
|
||||
|
||||
|
||||
## Sitemap Insert demo
|
||||
|
||||
|
||||
|
||||
|
||||
## Known Issues
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,131 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: openHAB VSCode Extension
|
||||
source: https://github.com/openhab/openhab-vscode/blob/master/docs/USAGE.md
|
||||
description: "The openHAB vscode extension provides useful features for configuration and maintenance of your openHAB environment."
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
You are able to configure the hostname and port for the Sitemap preview.
|
||||
|
||||
* openhab.host (mandatory), default: openhabianpi
|
||||
* openhab.port (optional), default: 8080
|
||||
|
||||
*openhab.host* will also work with the IP address of your openHAB instance, instead of the hostname.
|
||||
|
||||
These settings should work fine on Windows machines and openHAB installations using the recommended [openHABian](https://www.openhab.org/docs/installation/openhabian.html) setup.
|
||||
They should be edited if you use macOS or *NIX systems or manual openHAB installations.
|
||||
|
||||
To edit these settings, simply add overrides to either your user settings or your workspace settings in your Visual Studio Codes preferences.
|
||||
|
||||
For further informations on how to change your settings, visit the official [Visual Studio Code docs](https://code.visualstudio.com/docs/getstarted/settings).
|
||||
|
||||
### Configuration example (local)
|
||||
|
||||
```json
|
||||
{
|
||||
"openhab.host": "localhost",
|
||||
"openhab.port": 80
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration example (macOS)
|
||||
|
||||
```json
|
||||
{
|
||||
"openhab.host": "openhabianpi.local",
|
||||
"openhab.port": 8080
|
||||
}
|
||||
```
|
||||
|
||||
### Integration with openHAB REST API
|
||||
|
||||
This VSCode extension connects to the openHAB REST API by default.
|
||||
The connection is used to display list of Items in the left side tree view.
|
||||
It's also utilized for code completions.
|
||||
|
||||
If you're using this extension just for the syntax highlighting
|
||||
and don't want to involve the REST API, you can disable it by providing
|
||||
the following parameter in your User Settings (`Ctrl + Shift + S`):
|
||||
|
||||
```
|
||||
"openhab.useRestApi": false
|
||||
```
|
||||
|
||||
You may need to reload the VSCode window to take effect.
|
||||
|
||||
## Validating the Rules
|
||||
|
||||
This extension comes with Language Server Protocol support.
|
||||
Language servers allow you to add your own validation logic to files open in VS Code.
|
||||
openHAB from version `openHAB 2.2.0 Build #1065` (SNAPSHOT) has the Language Server exposed on `5007` port.
|
||||
openHAB 2.2 since build #1084 has LSP feature enabled in the runtime, so there are no additional steps for you to make it work.
|
||||
|
||||
In the unlikely case that your language server is running on a port other than the default one this is how it can be changed in the configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"openhab.remoteLspPort": 5007
|
||||
}
|
||||
```
|
||||
|
||||
If you don't want to have your openHAB files validated by Language Server, simply disable it in the extension:
|
||||
```json
|
||||
{
|
||||
"openhab.remoteLspEnabled": false
|
||||
}
|
||||
```
|
||||
|
||||
## Accessing remote openHAB
|
||||
|
||||
Accessing remote openHAB from service like myopenhab is not possible, given that you need an access to the file system in order to read and write to the configuration files.
|
||||
Although, you can access the Items and Things through the REST API.
|
||||
Note that LSP (content assist for rules and syntax validation) won't be exposed, so you'll need to disable it too.
|
||||
|
||||
The following configuration will allow you to access REST API remotely:
|
||||
|
||||
```
|
||||
"openhab.host": "https://home.myopenhab.org",
|
||||
"openhab.port": 80,
|
||||
"openhab.remoteLspEnabled": false,
|
||||
"openhab.username": "your_myopenhab_email",
|
||||
"openhab.password": "your_myopenhab_password",
|
||||
```
|
||||
|
||||
## Sitemap preview with Basic UI
|
||||
|
||||
openHAB VS Code Extension allows you to preview the [sitemap structure](https://www.openhab.org/docs/configuration/sitemaps.html) in the [Basic UI](https://www.openhab.org/docs/configuration/ui/basic/) running on your openHAB server instance.
|
||||
|
||||
If you have a sitemap file active in your editor and open Basic UI (`Ctrl + Alt + O` or editor title icon), you'll land directly on the sitemap you're working on.
|
||||
|
||||
You can optionally set `openhab.sitemapPreviewUI` parameter to `classicui` if you prefer Classic UI instead:
|
||||
```json
|
||||
{
|
||||
"openhab.sitemapPreviewUI": "classicui"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
You need to have openHAB server running in order to preview changes. The extension assumes that you access your openHAB config files from either:
|
||||
|
||||
Samba share (e.g. `\\OPENHABIANPI\openHAB-conf\`)
|
||||
Local folder (e.g. `c:\openhab\configuration`)
|
||||
|
||||
## Quick Karaf console access
|
||||
|
||||
|
||||
|
||||
This extension allows you to run openHAB Karaf console directly from the editor.
|
||||
Note that you need to have:
|
||||
|
||||
* `ssh` installed on your environment
|
||||
* Karaf exposed to the external interface
|
||||
* `openhab.host` configuration parameter set properly
|
||||
|
||||
This feature allows you to modify the new param and e.g. show the openHAB logs immediately:
|
||||
|
||||
```
|
||||
"openhab.karafCommand": "ssh openhab@%openhabhost% -p 8101 -t 'log:tail'",
|
||||
```
|
||||
|
Before Width: | Height: | Size: 1.6 MiB After Width: | Height: | Size: 1.6 MiB |
|
Before Width: | Height: | Size: 1.1 MiB After Width: | Height: | Size: 1.1 MiB |
|
Before Width: | Height: | Size: 415 KiB After Width: | Height: | Size: 415 KiB |
|
Before Width: | Height: | Size: 480 KiB After Width: | Height: | Size: 480 KiB |
|
Before Width: | Height: | Size: 2.8 MiB After Width: | Height: | Size: 2.8 MiB |
|
Before Width: | Height: | Size: 1.3 MiB After Width: | Height: | Size: 1.3 MiB |
Loading…
Reference in New Issue