This commit is contained in:
Paulchen-Panther 2021-03-15 20:01:40 +01:00
parent 48240bbd21
commit 709728aa81
84 changed files with 1 additions and 12376 deletions

View File

@ -188,30 +188,3 @@ jobs:
with:
name: windows
path: windows
######################
#### Documentation ###
######################
docs:
name: Documentation
runs-on: ubuntu-latest
defaults:
run:
working-directory: docs
steps:
- name: Checkout
uses: actions/checkout@v2
# Install dependencies
- name: Setup node 12
uses: actions/setup-node@v1
with:
node-version: '12'
# Build Docs
- name: Build docs
run: |
npm install -g yarn
yarn install
yarn docs:build

View File

@ -146,43 +146,6 @@ jobs:
with:
path: build/Hyperion-*
######################
#### Documentation ###
######################
Docs:
name: Documentation
runs-on: ubuntu-latest
defaults:
run:
working-directory: docs
steps:
- name: Checkout
uses: actions/checkout@v2
# Install dependencies
- name: Setup node 12
uses: actions/setup-node@v1
with:
node-version: '12'
# Build Docs
- name: Build docs
run: |
cd docs
npm install -g yarn
yarn install
yarn docs:build
# Deploy to gh-pages (only on tagged commit)
- name: Deploy to gh-pages
if: startsWith(github.event.ref, 'refs/tags')
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/dist
cname: docs.hyperion-project.org
################################
###### Publish Releases ########
################################
@ -190,7 +153,7 @@ jobs:
publish:
name: Publish Releases
if: startsWith(github.event.ref, 'refs/tags')
needs: [Linux, macOS, windows, Docs]
needs: [Linux, macOS, windows]
runs-on: ubuntu-latest
steps:
- name: Checkout

View File

Before

Width:  |  Height:  |  Size: 198 KiB

After

Width:  |  Height:  |  Size: 198 KiB

2
docs/.gitignore vendored
View File

@ -1,2 +0,0 @@
node_modules
dist

View File

@ -1,24 +0,0 @@
## Documentation
This folder contains the Hyperion documentation build files. It's written in Markdown with [VuePress](https://vuepress.vuejs.org/) as static site generator.
### Development
To edit or translate the documentation, it's not necessarily required to follow these steps (As we use Markdown). But if you want to check the results, please do so.
- Install latest [Node.js LTS](https://nodejs.org/en/)
- Open console
- Install Yarn `npm install -g yarn` (If this does not work - logout/login)
- Navigate with console to this directory
- Do `yarn install`
- Now you can start dev server with `yarn docs:dev`
- Open Browser and go to address `localhost:8080`
#### Notes
- If you want to view the deployable site locally run `yarn docs:serve`
- Do not rename files and folders while translating
- Copy/paste and translate also `.vuepress/config.js` at `themeConfig.locales`
- Changes in `.vuepress/config.js` may lead to a bugged dev server. Restart.
- To modify the sidebar pages checkout `.vuepress/config.js` at `themeConfig.sidebar`
### Production
To get a deployable version run
- `yarn docs:build` (while inside this folder)
- Files will be in `dist` folder

View File

@ -1,18 +0,0 @@
<template>
<div class="text-center img-margin">
<img class="zoomable img-shadow" :src="$withBase(src)" :alt="alt" />
<div class="no-mp sub-text">
<slot>{{alt}}</slot>
</div>
</div>
</template>
<script>
export default {
props: ["src", "alt"],
methods: {}
};
</script>
<style>
</style>

View File

@ -1,49 +0,0 @@
<template>
<div
:class="[baseClass,computedContainerClass]"
style="width:200px; height:180px; margin:10px; padding:5px 10px; background-color:#2b819a"
@click="goTo($withBase(to))"
>
<div style="width:100%">
<h3>{{title}}</h3>
</div>
<div class="sub-text flex flex-center">
<p>{{text}}</p>
</div>
</div>
</template>
<script>
export default {
props: ["title", "text", "to", "disabled"],
data() {
return {
baseClass: "card text-center cursor-pointer dark"
};
},
methods: {},
computed: {
computedContainerClass() {
return this.disabled == "" ? "main-section-disabled" : "";
}
},
methods: {
goTo(val) {
if (this.disabled != "") {
document.location.href = val;
}
}
}
};
</script>
<style>
.card {
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2);
transition: 0.3s;
}
.card:hover {
box-shadow: 0 8px 16px 0 rgba(0, 0, 0, 0.2);
}
</style>

View File

@ -1,290 +0,0 @@
module.exports = {
head: [
['link', { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/icons/favicon-16x16.png' }],
['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/icons/favicon-32x32.png' }],
['link', { rel: 'icon', type: 'image/png', sizes: '96x96', href: '/icons/favicon-96x96.png' }],
['link', { rel: 'icon', type: 'image/png', sizes: '128x128', href: '/icons/favicon-128x128.png' }],
['link', { rel: 'icon', type: 'image/ico', href: '/icons/favicon.ico' }],
// iPhone XR
['link', { rel: "apple-touch-startup-image", media: "(device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-828x1792.png" }],
// iPhone X, XS
['link', { rel: "apple-touch-startup-image", media: "(device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3)", href: "/icons/apple-launch-1125x2436.png" }],
// iPhone XS Max
['link', { rel: "apple-touch-startup-image", media: "(device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 3)", href: "/icons/apple-launch-1242x2688.png" }],
// iPhone 8, 7, 6s, 6
['link', { rel: "apple-touch-startup-image", media: "(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-750x1334.png" }],
// iPhone 8 Plus, 7 Plus, 6s Plus, 6 Plus
['link', { rel: "apple-touch-startup-image", media: "(device-width: 414px) and (device-height: 736px) and (-webkit-device-pixel-ratio: 3)", href: "/icons/apple-launch-1242x2208.png" }],
// iPhone 5
['link', { rel: "apple-touch-startup-image", media: "(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-640x1136.png" }],
// iPad Mini, Air, 9.7
['link', { rel: "apple-touch-startup-image", media: "(device-width: 768px) and (device-height: 1024px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-1536x2048.png" }],
// iPad Pro 10.5
['link', { rel: "apple-touch-startup-image", media: "(device-width: 834px) and (device-height: 1112px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-1668x2224.png" }],
// iPad Pro 11
['link', { rel: "apple-touch-startup-image", media: "(device-width: 834px) and (device-height: 1194px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-1668x2388.png" }],
// iPad Pro 12.9"
['link', { rel: "apple-touch-startup-image", media: "(device-width: 1024px) and (device-height: 1366px) and (-webkit-device-pixel-ratio: 2)", href: "/icons/apple-launch-2048x2732.png" }],
// PWA
['link', { rel: 'manifest', href: '/manifest.json' }],
['meta', { name: 'theme-color', content: '#2b81a0' }], // ???
['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
['meta', { name: 'apple-mobile-web-app-title', content: 'Hyperion Documentation' }],
['link', { rel: 'apple-touch-icon', sizes: '120x120', href: '/icons/apple-icon-120x120.png' }],
['link', { rel: 'apple-touch-icon', sizes: '152x152', href: '/icons/apple-icon-152x152.png' }],
['link', { rel: 'apple-touch-icon', sizes: '167x167', href: '/icons/apple-icon-167x167.png' }],
['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/icons/apple-icon-180x180.png' }],
['link', { rel: 'mask-icon', href: '/icons/safari-pinned-tab.svg', color: '#fff' }],
['meta', { name: 'msapplication-TileImage', content: '/icons/ms-icon-144x144.png' }], // probably invert
['meta', { name: 'msapplication-TileColor', content: '#2b81a0' }] // might not match with icon
],
dest: "./dist",
title: "Hyperion",
// removing this sections disables lang selector. But everything else works. Featue Request to merge with themeConfig.locales?
locales: {
"/": {
lang: 'en-US',
// Description of page does not work inside themeConfig
description: 'Hyperion Ambient Light documentation'
},
"/de/": {
lang: 'de-DE',
description: 'Hyperion Ambient Light Dokumentation'
}
},
themeConfig: {
/* algolia: {
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>'
},
*/
sidebarDepth: 3,
smoothScroll: true,
logo: '/hyperion-logo.png',
locales: {
'/': {
// text for the language dropdown
selectText: 'Languages',
// label for this locale in the language dropdown
label: 'English',
// Aria Label for locale in the dropdown
ariaLabel: 'Languages',
// text for last updated
lastUpdated: 'Last Updated',
// Seach placeholder
searchPlaceholder: 'Search...',
// Customising the header label
repoLabel: 'Contribute',
// custom text for edit link. Defaults to "Edit this page"
editLinkText: 'Edit this page on GitHub',
// config for Service Worker
serviceWorker: {
updatePopup: {
message: "New content is available.",
buttonText: "Refresh"
}
},
// The top navbar
nav: [
{ text: 'Home', link: '/' },
{ text: 'User', link: '/en/user/' },
{ text: 'Effects', link: '/en/effects/' },
{ text: 'Json API', link: '/en/json/' }
// { text: 'Addons API', link: '/en/addons/' }
],
sidebar: {
'/en/user/': getUserSidebar('General', 'Advanced'),
'/en/effects/': getEffectsSidebar('Effects', 'Effects UI'),
'/en/json/': getJsonSidebar('JSON', 'Misc'),
'/en/api/': getApiSidebar('Go back to')
// '/en/addons/': getAddonsSidebar('Addons', 'Addons UI')
}
},
'/de/': {
selectText: 'Sprachen',
label: 'Deutsch',
searchPlaceholder: 'Wer sucht...',
lastUpdated: 'Zuletzt Aktualisiert',
repoLabel: 'Mach mit',
editLinkText: 'Editiere diese Seite auf Github',
serviceWorker: {
updatePopup: {
message: "Neuer Inhalt ist verfügbar.",
buttonText: "Aktualisieren"
}
},
nav: [
{ text: 'Startseite', link: '/de/' }
//{ text: 'Benutzer', link: '/de/user/' }
//{ text: 'Effects', link: '/en/effects/' },
//{ text: 'Json API', link: '/en/json/' }
// { text: 'Addons API', link: '/en/addons/' }
],
// '/de/user/': getUserSidebar('Allgemein', 'Erweitert'),
// '/de/effects/': getEffectsSidebar('Effekte', 'Effekt UI'),
// '/de/json/': getJsonSidebar('JSON', 'Misc'),
// '/de/api/': getApiSidebar('Gehe zurück zu')
// '/en/addons/': getAddonsSidebar('Addons', 'Addons UI')
}
},
// Customising the header label
// Defaults to "GitHub"/"GitLab"/"Bitbucket" depending on `themeConfig.repo`
repoLabel: 'Contribute',
// Optional options for generating "Edit this page" link
// if your docs are in a different repo from your main project:
docsRepo: 'hyperion-project/hyperion.ng',
// if your docs are not at the root of the repo:
docsDir: 'docs/docs',
// if your docs are in a specific branch (defaults to 'master'):
docsBranch: 'master',
// defaults to false, set to true to enable
editLinks: true,
// default value is true. Allows to hide next page links on all pages
nextLinks: true,
// default value is true. Allows to hide prev page links on all pages
prevLinks: true,
// custom text for edit link. Defaults to "Edit this page"
//editLinkText: 'Edit this page on GitHub'
},
plugins: [
// https://vuepress.github.io/en/plugins/medium-zoom/
[
'vuepress-plugin-medium-zoom',
{
selector: '.zoomable',
delay: 1000,
options: {
margin: 24,
background: '#000000bf',
scrollOffset: 0,
}
}
],
// https://vuepress.github.io/en/plugins/redirect
[
'vuepress-plugin-redirect',
{
locales: true
}
],
// https://vuepress.vuejs.org/plugin/official/plugin-pwa.html#install
[
'@vuepress/pwa', {
serviceWorker: true,
updatePopup: true
}
],
// https://v1.vuepress.vuejs.org/plugin/official/plugin-back-to-top.html
[
'@vuepress/back-to-top'
],
[
'vuepress-plugin-serve'
]
]
}
function getUserSidebar (groupA, groupB) {
return [
{
title: groupA,
collapsable: false,
children: [
'',
'Installation',
'Configuration',
'LedDevices',
'HyperBian',
]
},
{
title: groupB,
collapsable: false,
children: [
'advanced/Advanced',
'advanced/Support',
]
}
]
}
function getEffectsSidebar (groupA, groupB) {
return [{
title: groupA,
collapsable: false,
children: [
'',
'API',
'OurFirstEffect',
]
},
{
title: groupB,
collapsable: false,
children: [
'../api/Ui'
]
}
]
}
function getJsonSidebar (groupA, groupB) {
return [{
title: groupA,
collapsable: false,
children: [
'',
'ServerInfo',
'Control',
'Authorization',
'Subscribe',
]
},
{
title: groupB,
collapsable: false,
children: [
'../api/Detect',
'../api/Guidelines'
]
}
]
}
function getApiSidebar (groupA) {
return [
{
title: groupA,
collapsable: false,
children: [
'../effects/',
'../json/'
]
}
]
}
function getAddonsSidebar (groupA, groupB) {
return [{
title: groupA,
collapsable: false,
children: [
'',
'API',
'OurFirstAddon',
]
},
{
title: groupB,
collapsable: false,
children: [
'../api/Ui'
]
}
]
}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 247 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 282 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 287 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 344 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 352 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 389 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 498 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 125 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 150 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 195 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.1 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 152 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 80 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 155 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 72 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.8 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

View File

@ -1,36 +0,0 @@
{
"name": "Hyperion Documentation",
"short_name": "Hyperion Documentation",
"start_url": ".",
"display": "standalone",
"background_color": "#fff",
"theme_color": "#2b81a0",
"description": "All you want to know about Hyperion",
"icons": [
{
"src": "icons/icon-128x128.png",
"sizes": "128x128",
"type": "image/png"
},
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "icons/icon-256x256.png",
"sizes": "256x256",
"type": "image/png"
},
{
"src": "icons/icon-384x384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}

View File

@ -1,48 +0,0 @@
// global css as stylus
.text-center
text-align center
.sub-text
color rgb(94, 94, 94)
font-size 90%
.cursor-pointer
cursor: pointer
.dark
color white
.sub-text
opacity 0.8
color: white
.flex
display: flex
flex-wrap: wrap
.flex-center
justify-content center
.no-decoration
text-decoration none
.main-section-disabled
background-color grey !important
color lightgrey !important
cursor not-allowed !important
pointer-events none
// hide Hyperion TITLE
.site-name
display none !important
.no-mp
margin 0 !important
padding 0 !important
// ImageWrap component
.img-margin
margin 10px 5px
p
margin 0
.img-shadow
box-shadow 1px 1px 5px 0 rgba(0,0,0,0.4)

View File

@ -1,9 +0,0 @@
// default styles: DO NOT ADD custom global css here, use index.styl instead
// original $accentColor = #3eaf7c
$accentColor = #2b819a
// default values 10.2019
// $accentColor = #3eaf7c
// $textColor = #2c3e50
// $borderColor = #eaecef
// $codeBgColor = #282c34

View File

@ -1,17 +0,0 @@
---
sidebar: false
---
<img :src="$withBase('/hyperion-logo.png')" alt="Hyperion Logo">
Welcome in the colorful world of Hyperion. Please choose the documentation you want to view.
<div class="flex flex-center no-decoration">
<MainSection title="User" text="Installation, configuration and advanced informations" to="/en/user" />
<MainSection title="Effects" text="Learn how to create an effect" to="/en/effects" />
<MainSection title="JSON API" text="Learn how to interact with the API" to="/en/json" />
</div>
::: tip
You can select another translation at the top.
:::

View File

@ -1,17 +0,0 @@
---
sidebar: false
---
<img :src="$withBase('/hyperion-logo.png')" alt="Hyperion Logo">
Willkommen in der bunten Welt von Hyperion. Bitte wähle aus, welche Dokumentation du einsehen möchtest.
<div class="flex flex-center no-decoration">
<MainSection title="Benutzer" text="Installation, Konfiguration und erweiterte Informationen" to="/de/user" disabled/>
<MainSection title="Effekte" text="Lerne wie man Effekte entwickelt" to="/de/effects" disabled />
<MainSection title="JSON API" text="Lerne wie du mit der API interagieren kannst" to="/de/json" disabled />
</div>
::: warning Unvollständig
Leider ist die Dokumentation in der ausgewählten Sprache nicht vollständig verfügbar. Wenn du mithelfen möchtest dies zu ändern, geht es [hier weiter](https://github.com/hyperion-project/hyperion.ng/blob/master/docs/README.md).
:::

View File

@ -1,57 +0,0 @@
# Installiere Hyperion
Hyperion unterstützt zahlreiche Plattformen zur Installation und wird als Paket oder .zip bereitgestellt.
## Voraussetzungen
### Unterstützte Systeme
* Raspberry Pi (Siehe [HyperBian](/en/user/HyperBian), derzeit nur auf Englisch)
* Debian 9 | Ubuntu 16.04 oder neuer
* Mac OS
* Windows 10
**Einige arm Geräte haben eine reduzierte Untersützung der Funktion des mitschneidens des Bildschirms**
### Unterstützte Browser
Hyperion wird durch ein Web Interface konfiguriert und gesteuert.
* Chrome 47+
* Firefox 43+
* Opera 34+
* Safari 9.1+
* Microsoft Edge 14+
::: warnung Internet Explorer
Internet Explorer ist nicht unterstützt.
:::
## Installation von Hyperion
* Raspberry Pi man kann [HyperBian](/en/user/HyperBian.md) für ein neues System nutzen. Alternativ kann es auf einem bestehenden System installiert werden
* Wir stellen Installationspakete (.deb) bereit um Hyperion mit nur einem Klick auf Debian/Ubuntu basierten Systemen zu installieren.
* Mac OSX - derzeit nur eine Zip-Datei mit Binärdaten
* Windows 10 - Lade die Windows-AMD.64.exe von der [Release page](https://github.com/hyperion-project/hyperion.ng/releases) herunter und installiere es.
### Debian/Ubuntu
Für Debian/Ubuntu stellen wir eine .deb Datei bereit. Damit geschieht die Installation automatisch. \
Lade die Datei von der [Release page](https://github.com/hyperion-project/hyperion.ng/releases) herunter. \
Installiere über die Kommandozeile indem du \
`sudo apt install ./Hyperion-2.0.0-Linux-x86_64.deb` \
eintippst. Hyperion kann jetzt über das Startmenü gestartet werden.
### Fedora
Für Fedora stellen wir eine .rpm Datei bereit. Damit geschieht die Installation automatisch. \
Lade die Datei von der [Release page](https://github.com/hyperion-project/hyperion.ng/releases) herunter. \
Installiere über die Kommandozeile indem du \
`sudo dnf install ./Hyperion-2.0.0-Linux-x86_64.rpm` \
eintippst. Hyperion kann jetzt über das Startmenü gestartet werden.
### Windows 10
Für Windows 10 stellen wir eine .exe Datei bereit. Damit geschieht die Installation automatisch. \
Lade die Datei von der [Release page](https://github.com/hyperion-project/hyperion.ng/releases) herunter. \
Installiere über das ausführen der .exe Datei. Hyperion kann jetzt über das Startmenü gestartet werden.
## Deinstallieren von Hyperion
In Debian/Ubuntu kann man Hyperion mit diesem Kommando deinstallieren \
`sudo apt remove hyperion` \
In Windows erfolgt die Deinstallation über die Systemsteuerung.
### Hyperion lokale Daten
Hyperion speichert lokale Daten in dem "Home"-Ordner (Ordner `.hyperion`).

View File

@ -1,210 +0,0 @@
# Addon API
Overview of the API. Get access to these functions by importing the `hapi` module `import hapi`.
| Function | Returns | Comment |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| hapi.abort() | bool | Check if we should abort the script, True on abort request else false |
| hapi.log() | - | Print a log message to the Hyperion log. See [hapi.log()](#hapi-log) |
| hapi.registerCallback() | - | Register a function with a callback function. See [hapi.registerCallback()](#hapi-registercallback) |
| hapi.unregisterCallback() | - | Unregister a function from callback. See [hapi.unregisterCallback()](#hapi-unregistercallback) |
| hapi.getComponentState() | int | Get current state of a component. See [hapi.getComponentState()](#hapi-getcomponentstate ) |
| hapi.setComponentState() | bool | Enable or disable a component. See [hapi.setComponentState()](#hapi-setcomponentstate) |
| hapi.getSettings() | data | Get the current user settings for your addon. See [hapi.getSettings()](#hapi-getsettings) |
| hapi.setColor() | - | Set a color. See [hapi.setColor()](#hapi-setcolor) |
| hapi.setEffect() | int | Start effect by name. See [hapi.setEffect()](#hapi-seteffect ) |
| hapi.getPriorityInfo() | dict | Get info about a priority. See [hapi.getPriorityInfo()](#hapi-getpriorityinfo) |
| hapi.getAllPriorities() | list | Get all registered priorities. See [hapi.getAllPriorities()](#hapi-getallpriorities) |
| hapi.getVisiblePriority() | int | Get current visible priority. See [hapi.getVisiblePriority()](#hapi-getvisiblepriority) |
| hapi.setVisiblePriority() | bool | Select a specific priority. See [hapi.setVisiblePriority()](#hapi-setvisiblepriority) |
| hapi.getAdjustmentList() | list | Get a list of all adjustment ids. See [hapi.getAdjustmentList()](#hapi-getadjustmentlist) |
| hapi.getBrightness() | int | Get current brightness. See [hapi.getBrightness()](#hapi-getbrightness) |
| hapi.setBrightness() | bool | Set new brightness. See [hapi.setBrightness()](#hapi-setbrightness) |
## Data transformation cheatsheet
As we need to transform "UI elements"-data from `json` to `python`, here a cheatsheet how the transformation is done.
| Json | Python |
| :-----: | :----: |
| boolean | int |
| integer | int |
| number | float |
| string | str |
| array | list |
| object | dict |
## Methods
### hapi.log()
Write a message to the Hyperion log. Your addon name will be automatically prepended to all messages!
`hapi.log(msg, lvl)`
| Argument | Type | Comment |
| msg | str | The message you want to print as string |
| lvl | enum | Optional: Print message with a specific log lvl. `LOG_INFO` = Info, `LOG_WARNING` = Warning, `LOG_ERROR` = Error, `LOG_DEBUG` = Debug. **Defaults to Debug** |
### hapi.registerCallback()
To listen for specific Hyperion events you can register callbacks.
`hapi.registerCallback(callbackType, connectFunction)`
| Argument | Type | Comment |
| ----------------------------------------- | ---- | --------------------------------------------------------------------------------------------------- |
| callbackType | Enum | Callbacks: `ON_COMP_STATE_CHANGED`, `ON_SETTINGS_CHANGED`, `ON_VISIBLE_PRIORITY_CHANGED` |
| connectFunction | - | A previously defined function which will be used to deliver the callback |
| callbackType: ON_COMP_STATE_CHANGED | - | When comp state changes, arg1 `comp` component as str, arg2 `newState` as int |
| callbackType: ON_SETTINGS_CHANGED | - | When user saved new settings, reload settings [hapi.getSettings()](#hapi.getsettings) |
| callbackType: ON_VISIBLE_PRIORITY_CHANGED | - | Is called whenever the visible priority changes, argument `priority` of type int (the new priority) |
``` python
# Example implementation with log output
import hapi
def onCompStateChanged(comp, newState):
hapi.log("The component "+comp+" changed state to:"+str(newState))
def onSettingsChanged():
hapi.log("New settings! Do something!")
def onVsibilePriorityChanged(newPriority):
hapi.log("The new visible priority is: "+str(newPriority))
hapi.registerCallback(ON_COMP_STATE_CHANGED, onCompStateChanged)
hapi.registerCallback(ON_SETTINGS_CHANGED, onSettingsChanged)
hapi.registerCallback(ON_VISIBLE_PRIORITY_CHANGED, onVsibilePriorityChanged)
```
### hapi.unregisterCallback()
You can also unregister a callbackType again. You can register and unregister as often you need it. Usually you won't need it, but for completion here it is! After unregister the connected function does no longer react upon callbacks
`hapi.unregisterCallback(callbackType)`
| Argument | Type | Comment |
| ------------ | ---- | ------------------------------------------------------------------------------------ |
| callbackType | Enum | One of `ON_COMP_STATE_CHANGED`, `ON_SETTINGS_CHANGED`, `ON_VISIBLE_PRIORITY_CHANGED` |
### hapi.getComponentState()
Get the current state of a component.
`hapi.getComponentState(comp)`
| Argument | Type | Comment |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| comp | int | The component ID one of `COMP_ALL COMP_SMOOTHING COMP_BLACKBORDER COMP_LEDDEVICE COMP_GRABBER COMP_V4L`, prefixed with `COMP_`. See explanation here [Component IDs explained](/en/json/control#components-ids-explained) |
| @return | int | `True` if enabled, `False` if disabled, `-1` if not found |
### hapi.setComponentState()
Set a Hyperion component to a new state. This method writes a debug message on each call!
`hapi.setComponentState(comp, enable)`
| Argument | Type | Comment |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| comp | int | The component ID one of `COMP_ALL COMP_SMOOTHING COMP_BLACKBORDER COMP_LEDDEVICE COMP_GRABBER COMP_V4L`, prefixed with `COMP_`. See explanation here [Component IDs explained](/en/json/control#components-ids-explained) |
| enable | int | True to enable it, False to disable it |
| @return | bool | True if the requested component was found else false |
### hapi.getSettings()
Get the current user settings data for your addon. The returned data contains all settings that has been transformed from JSON to python data types. See the table below how they are transformed.
`hapi.getSettings()`
| Json | Python |
| :-----: | :----: |
| boolean | int |
| integer | int |
| number | float |
| string | str |
| array | tuple |
| object | dict |
**Basics** \
The root data type is usually of type object which will be transformed to a python dict, so we use the dict syntax to get the value. The fallback parameter should be defined wisely, if the value is not found it will be used instead.
``` python
import hapi
# Get a bool value of a dict
myBoolValue = MySettings.get('MyBoolOption', True)
# Get a int value of a dict
myIntValue = MySettings.get('MyIntOption', 20)
# Get a float value of a dict
myFloatValue = MySettings.get('MyFloatOption', 15.7)
# Get a string value of a dict
myStringValue = MySettings.get('MyStringOption', 'MyFallbackString')
# Get a tuple of a dict
# Two RGB colors would look like the following. A tuple that contains 2 other tuples where each contains 3 int values
myListValue = MySettings.get('MyListOption', ())
# Here a colorpicker example
myColorValue = MySettings.get('MyColorPicker', (255,0,0))
# Here an array(tuple) of multiple colorpickers
myColorValues = MySettings.get('MyColorPickers', ((255,0,0),(0,255,0)) )
```
### hapi.setColor()
Set a RGB color value with timeout at the given priority.
`hapi.setColor(red, green, blue, timeout, priority)`
| Argument | Type | Comment |
| -------- | ---- | ---------------------------------------------------------------------- |
| red | int | Red 0-255 |
| green | int | Green 0-255 |
| blue | int | Blue 0-255 |
| timeout | int | Optional: Set a specific timeout in ms. Defaults to -1 (endless) |
| priority | int | Optional: Set the color at a specific priority channel. Defaults to 50 |
### hapi.setEffect()
Start an effect by name with timeout at the given priority.
`hapi.setEffect(effectName, timeout, priority)`
| Argument | Type | Comment |
| ---------- | ---- | ---------------------------------------------------------------------- |
| effectName | str | The name of the effect |
| timeout | int | Optional: Set a specific timeout in ms. Defaults to -1 (endless) |
| priority | int | Optional: Set the color at a specific priority channel. Defaults to 50 |
| @return | int | `0` on success, `-1` on failure (eg not found) |
### hapi.getPriorityInfo()
Get priority info for the given priority.
`hapi.getPriorityInfo(priority)`
| Argument | Type | Comment |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------ |
| priority | int | The priority you want information for |
| @return | dict | A dict with fields `priority` as int, `timeout` as int, `component` as str, `origin` as str, `owner` as str. |
### hapi.getAllPriorities()
Get all registered priorities.
`hapi.getAllPriorities()`
| Argument | Type | Comment |
| :------: | :---: | :-------------------------------------------------------------------------: |
| @return | tuple | A tuple of all priorities that has been registered (type int) `(1,240,255)` |
### hapi.getVisiblePriority()
Get the current visible priority.
`hapi.getVisiblePriority()`
| Argument | Type | Comment |
| -------- | ---- | ------------ |
| @return | int | The priority |
### hapi.setVisiblePriority()
Set a specific priority to visible. Returns `True` on success or `False` if not found.
`hapi.setVisiblePriority(priority)`
| Argument | Type | Comment |
| -------- | ---- | ---------------------------------------------------- |
| priority | int | The priority to set |
| @return | bool | `True` on success, `False` on failure (eg not found) |
### hapi.getAdjustmentList()
Returns a list of all available adjustment ids. These ids are used to apply changes to different calibration profiles.
`hapi.getAdjustmentList()`
| Argument | Type | Comment |
| -------- | ---- | ---------------------- |
| @return | list | List of adjustment ids |
### hapi.getBrightness()
Get the brightness of a given adjustment id. If no id is provided it will return the brightness of primary adjustment (e.g. first). See also [hapi.getAdjustmentList()](#hapi-getadjustmentlist).
`hapi.getBrightness(id)`
| Argument | Type | Comment |
| -------- | ---- | ----------------------------------------------------------------------------------------------------------------------- |
| id | str | Optional: Get the brightness of a specific adjustment id, if not given it will return the primary adjustment brightness |
| @return | int | The brightness between `0` and `100` (considered as %). Returns `-1` if the adjustment id is not found |
### hapi.setBrightness()
Set the brightness for the given adjustment id. If no id is provided it will set all available adjustment ids to the given brightness. See also getAdjustmentList()
`hapi.setBrightness(brightness, id)`
| Argument | Type | Comment |
| :--------: | :---: | :-----------------------------------------------------------------------------------------------------: |
| brightness | int | The brightness value between `0` and `100` |
| id | str | Optional: Target a specific adjustment id, if not set it will apply the brightness to all available ids |
| @return | bool | `True` on success, `False` on failure (eg given adjustment id not found) |

View File

@ -1,87 +0,0 @@
# Our first addon
You want to write an addon? You have no clue about everything? Perfect, the next steps will explain you everything you need to know. Also Python beginners are invited. Let's start with the addon types.
[[toc]]
## Addon types
Currently there are 2 types of Addons.
* Service
* Module
A service addon runs usually the whole time (if enabled), it starts and stops with the execution of Hyperion. Additional it has settings that can be configured from the user to fit their needs. This can be an IP address to another service, a time to trigger, or anything else that you will discover from the Addon API
A module provides utility methods which can be imported from a service addon to be used. Examples are Python packages from the PyPi repository like httplib2, which makes the developer life easier when working with HTTP requests. Instead implementing everything on your own you can rely on the work of others with well tested modules from the Python community. You can also create modules on your own if you think the code can be reused in other service addons.
## Development setup
All you need is:
* An installed and running Hyperion. You need access to the filesystem where Hyperion has been installed
* An editor to write code (recommended [Visual Studio Code](https://code.visualstudio.com/)) for Windows/Linux/Mac)
### Folder layout
The follow files are part of an addon.
| File | language | Comment |
| ------------------- | -------------------------------------- | --------------------------------------------------------------------------- |
| service.py | [Python](https://www.python.org/) | Required for `service` addons. Entry point, this is where your code goes to |
| addon.json | [JSON](http://www.json.org/) | The meta data file required for all addons |
| settingsSchema.json | [JSON Schema](http://json-schema.org/) | Required for `service` addons. Options UI. [Read more](/en/api/ui.md) |
| lib | Folder | Required for `module` addons. Entry point for modules |
### Create a new service Addon
To create a service addon you need to follow a simple structure.
- Navigate to ~/.hyperion/addons (folder in your home directory)
- Think about a short "id", this id needs to be unique and should just contain letters (English), lowercase no whitespace Example: `kodicon` `plexcon` `timer` `cec`
- Create a folder with your id and prepend `service.`. Example: `service.kodicon` `service.timer` `service.cec`
- Inside this folder create a file called `service.py`, this is where your addon code goes to
- Create a file called `settingsSchema.json`, this will represent our options
- Create a new file called `addon.json` and add [metadata](#metadata|)
- That's it!
::: tip
A prepared service playground addon can be downloaded from the repository. This shows the basic usage of the API but also how option UI works
:::
### Metadata
The metadata file called addon.json is a description of your addon to declare name, version, dependencies, support URL, sourcecode URL and more. This file is parsed by Hyperion to provide users required informations and download updates accordingly.
| Property | Type | Comment |
| ------------ | ------ | ---------------------------------------------------------------------- |
| name | String | User friendly name of your addon |
| description | String | What does this addon as a brief overview |
| id | String | The unique id |
| version | String | The current version of your addon. [Semver 2.0.0](https://semver.org/) |
| category | Array | Add the addon to a category. Available `utility` |
| dependencies | Object | You can depend on modules / a specific minimum Hyperion version. |
| changelog | Array | Array of Objects with notes |
| provider | String | Author of this addon |
| support | String | A URL for support. |
| source | String | A URL where the source code is hosted |
| licence | String | Licence type, can be MIT, GPL, LGPL |
Here a version for copy and paste
``` json
{
"name":"My addon Name",
"description" : "What does my addon as a brief overview",
"id":"service.myid",
"version" : "0.1.0",
"category" : "utility",
"dependencies" :{"hyperion" : "2.0.0"},
"changelog" : [{"0.1.0 Crunchy Cudator":"-New featrues -bugfixs -other stuff"}],
"provider":"hyperion-project",
"support":"URL to hyperion-project.org Forum thread",
"source" :"URL to source code",
"licence" : "MIT"
}
```
### Addon categories
Addons can be assigned to a category for better sorting. Select the best matching
* **utility** A utility is usually a smaller addon, which does very basic tasks. It doesn't connect to another software. For example the Wake On LAN addon is a utility.
* **integration** A integration addon interfaces with another software to listen for specific API events which triggers now actions on the Hyperion side or vice versa. Example is the Kodi addon
* You can suggest new categories!
### Development
Enough preparation stuff, let's start! \
It's highly recommended to work/read once through a Python tutorial which explains you the principals of Python if you are new to Python.
* New to Python? No problem, here is a interactive tutorial where you can read, write and execute your first python scripts inside your browser [learnpython](https://www.learnpython.org/), available in 7 languages!
* Good beginner guide: [Python course EN](https://www.python-course.eu/python3_interactive.php). [Python Kurs DE](https://www.python-kurs.eu/python3_interaktiv.php). It's not necessary (nor possible) to understand everything, but the first pages are very helpful as a start!

View File

@ -1,10 +0,0 @@
# Addons
Hyperion has an addon engine that allows you to extend the functionality of Hyperion. It is written in Python and has a specific task like connecting to a third party software and listen for events to apply actions based on addon settings at the Hyperion API.
[[toc]]
## API
An API documentation is available here: [Addon API](/en/addons/api.md)
## Our first Addon
A guide for people that want to learn and write something: [Our first Addon](/en/addons/OurFirstAddon.md)

View File

@ -1,57 +0,0 @@
# Detect Hyperion
Hyperion announces it's services on the network, via ZeroConf and SSDP.
[[toc]]
## SSDP
**S**imple**S**ervice**D**iscovery**P**rotocol
([SSDP](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol)) is the
discovery subset of UPnP. The implementation is lighter than ZeroConf as it just needs a
UDP Socket without any further dependencies.
### SSDP-Client Library
Here are some example client libraries for different programming languages (many others available):
* [NodeJS](https://github.com/diversario/node-ssdp#usage---client)
* [Java](https://github.com/resourcepool/ssdp-client#jarpic-client)
### Usage
With a given SSDP-client library, you can use the following USN / service type:
`urn:hyperion-project.org:device:basic:1`
Some headers from the response will include:
* **Location**: The URL of the webserver
* **USN**: The unique id for this Hyperion instance, it will remain the same after system restarts or Hyperion updates
* **HYPERION-FBS-PORT**: The port of the flatbuffers server
* **HYPERION-JSS-PORT**: The port of the JsonServer
* **HYPERION-NAME**: The user defined name for this server
As the data changes (e.g. network adapter IP address change), new updates will be automatically announced.
## Zeroconf
Also known as [Apple Bonjour](https://en.wikipedia.org/wiki/Bonjour_(software)) or [Avahi](https://en.wikipedia.org/wiki/Avahi_(software)). Hyperion is detectable through zeroconf.
**Hyperion publishes the following informations:**
* **_hyperiond-http._tcp**: Hyperion Webserver (HTTP+Websocket)
* **_hyperiond-json._tcp**: Hyperion JSON Server (TcpSocket)
* **_hyperiond-flatbuf._tcp**: Hyperion Flatbuffers server (Google Flatbuffers)
You get the IP address, hostname, port and the Hyperion instance name (before the @ for
the full name). As this works realtime you can always have an up to date list of available
Hyperion servers.
### TXT RECORD
Each published entry contains at least the following data in the txt field:
* **id**: A static unique id to identify an Hyperion instance.
* **version**: Hyperion version.
### Test Clients
There are several clients available for testing like the
[avahi-browse](http://manpages.ubuntu.com/manpages/bionic/man1/avahi-browse.1.html) a
commandline tool for Ubuntu/Debian. Example command
``` bash
sudo apt-get install avahi-browse && avahi-browse -r _hyperiond-http._tcp
```
<ImageWrap src="/images/en/avahi-browse.jpg" alt="Searching for Hyperion Server with Avahi cli" />

View File

@ -1,23 +0,0 @@
# Guidelines
Improve the user experience with Hyperion by following these guidelines.
[[toc]]
## Priority Guidelines
Please adhere to the following priority guidelines to avoid user confusion and ensure
the best user experience possible:
The user expects that an effect or color should be higher in priority (lower in value)
than capturing, as colors/effects are usually run intermittently.
| Type | Priority/Range | Recommended | Comment |
| :---------------------: | :------------: | :---------: | :----------------------------------------: |
| Boot Effect/Color | 0 | - | Blocked |
| Web Configuration | 1 | - | |
| **Remote Control** | **2-99** | **50** | Set effect/color/single image |
| **Image Streaming** | **100-199** | **150** | For image streams (Flatbuffer/Protobuffer) |
| Boblight | 201 | - | |
| USB Capture | 240 | - | |
| Platform Capture | 250 | - | |
| Background Effect/Color | 254 | - | |
| Reserved | 255 | - | |

View File

@ -1,250 +0,0 @@
# Graphical User Interface
We use a JSON schema to create a user-friendly GUI and validate the input to prevent wrong or unwanted data that will be consumed by your python file. Each python file requires a GUI schema.
::: tip
If you have never written JSON syntax, we recommend a short introduction. [Here](https://www.digitalocean.com/community/tutorials/an-introduction-to-json) and/or [Here (technical)](http://www.json.org/)
:::
[[toc]]
## UI elements
Each UI element has a specific schema. The schema allows you to give the element a label and validate user input by providing for example a minimum and a maximum number for an element of type number. A minimum count of colors, a default value (required!) or even to show/hide an element based on the value of another element.
### Checkbox
Show a checkbox.
``` json
"swirl_enabled" :{
"type" : "boolean",
"title" : "edt_eff_swirl_enabled",
"default" : false
}
```
The option `swirl_enabled` will be of type boolean with title `edt_eff_swirl_enabled` ([Titles will be translated](#translation)). The `default` sets the option to the defined default value, required!.
### String
An input field which accepts all kind of characters
``` json
"swirl_name" :{
"type" : "string",
"title" : "edt_eff_swirl_name",
"default" : "A cool placeholder name"
}
```
The option `swirl_name` will be of type string with title `edt_eff_swirl_name` ([Titles will be translated](#translation)). The `default` sets the option to the defined default value, required!. \
**Optional**
* Add `"minLength" : 5` to force a minimum length of 5. Be aware that the default value matches
* Add `"maxLength" : 9` to force a maximum length of 9. Be aware that the default value matches
* Add `"enum" : ["Amazing1","Amazing","Amazing3"]` Renders the input as a select box where the user can choose one of the defined options.
### Integer
An input field for integer
``` json
"swirl_count" :{
"type" : "integer",
"title" : "edt_eff_swirl_count",
"default" : 5
}
```
The option `swirl_count` will be of type integer with title `edt_eff_swirl_count` ([Titles will be translated](#translation)). The `default` sets the option to the defined default value, required!. \
**Optional**
* Add `"minimum" : 5` to force a minimum value in case it shouldn't be lower
* Add `"maximum" : 9` to force a maximum value in case it shouldn't be higher
* Add `"step" : 2,` to define a alternate stepping of value. If not given, defaults to `1`. This doesn't prevent values which are "outside" of the step, it's more a helper if you use up/down keys and higher or smaller steps are wanted.
### Number
A input field for numbers (float)
``` json
"swirl_spread" :
{
"type" : "number",
"title" : "edt_eff_swirl_spread",
"default" : 7.0
}
```
The option `swirl_spread` will be of type number (float) with title `edt_eff_swirl_spread` ([Titles will be translated](#translation)). The `default` sets the option to the defined default value, required!. \
**Optional**
* Add `"minimum" : 5.0` to force a minimum value in case it shouldn't be lower
* Add `"maximum" : 9.6` to force a maximum value in case it shouldn't be higher
* Add `"step" : 0.1,` to define a alternate stepping of value. If not given, defaults to `1.0`. This doesn't prevent values which are "outside" of the step, it's more a helper if you use up/down keys and higher or smaller steps are wanted.
### Select
Create a select element, where you can select one of the `enum` items. Default is required!
``` json
"candles": {
"type": "string",
"title":"edt_eff_whichleds",
"enum" : ["all","all-together","list"],
"default" : "all"
}
```
### Array
Creates an array input with the given properties at `items`. You can nest inside all kind of options
``` json
"countries": {
"type": "array",
"uniqueItems": true,
"title" : "edt_eff_countries",
"items": {
"type": "string",
"title": "edt_eff_country"
},
"default":["de","at"]
}
```
The option `countries` will be of type array (in python it's a python tuple) (shown as array where you can add or remove properties, in this case a string input field with the title `edt_eff_country"`) with the title `edt_eff_swirl_countries` ([Titles will be translated](#translation)). The `default` sets the option to the defined default value. Required! \
**Optional**
* Add `"uniqueItems": true` if you want to make sure that each item is unique
* Add `"minItems": 2` to force a minimum items count of the array
* Add `"maxItems": 6` to force a maximum items count of the array
### Array - Multiselect
Create a selection where multiple elements from `ènum` can be selected. Default value is not required.
``` json
"countries": {
"type": "array",
"title" : "edt_eff_countries",
"uniqueItems": true,
"items": {
"type": "string",
"enum": ["de","at","fr","be","it","es","bg","ee","dk","fi","hu","ie","lv","lt","lu","mt","nl","pl","pt","ro","sl","se","ch"]
},
"default":["de","at"],
"propertyOrder" : 1
},
```
### Array - Colorpicker RGB
Creates a RGB colorpicker.
``` json
"color" : {
"type": "array",
"title" : "edt_eff_color",
"format":"colorpicker",
"default" : [255,0,0],
"items":{
"type":"integer",
"minimum": 0,
"maximum": 255
},
"minItems": 3,
"maxItems": 3
}
```
The option `color` will be of type array (shown as RGB colorpicker) with the title `edt_eff_color` ([Titles will be translated](#translation)). This colorpicker will be set to initial red.
### Array - Colorpicker RGBA
Creates a RGBA colorpicker. Think twice brefore you provide a RGBA picker, the use case is limited.
``` json
"color" : {
"type": "array",
"title" : "edt_eff_color",
"format":"colorpickerRGBA",
"default" : [255,0,0,0.5],
"minItems": 4,
"maxItems": 4
}
```
The option `color` will be of type array (shown as RGBA colorpicker) with the title `edt_eff_color` ([Titles will be translated](#translation)). This colorpicker will be set to red with 50% alpha initial. Required to add a default color.
## More beautification
To organize your UI better and make it prettier we provide a set of additional keywords.
### Dependencies
Hide/Show a specific option based on the value of another option
``` json{12}
"enable-second": {
"type": "boolean",
"title":"edt_eff_enableSecondSwirl",
"default": false,
"propertyOrder" : 1
},
"random-center2": {
"type": "boolean",
"title":"edt_eff_randomCenter",
"default": false,
"options": {
"dependencies": {
"enable-second": true
}
}
}
```
The option `random-center2` is NOT shown until the option `enable-second` is set to true. This also works with numbers, integers and strings.
### Order
As each option is a Object and the sort order for Objects is random you need to set an order on your own. Add a `propertyOrder` key.
``` json{5,11}
"enable-second": {
"type": "boolean",
"title":"edt_eff_enableSecondSwirl",
"default": false,
"propertyOrder" : 1
},
"random-center2": {
"type": "boolean",
"title":"edt_eff_randomCenter",
"default": false,
"propertyOrder" : 2
}
```
The option `enable-second` will be first, `random-center2` second.
### Field appends
You want a specific unit at the end of a field like "s", "ms" or "percent"? Just add a `append` with the wanted unit.
``` json{5}
"interval": {
"type": "integer",
"title":"edt_eff_interval",
"default": 5,
"append" : "edt_append_s",
"propertyOrder" : 1
}
```
This will add a "s" for seconds to the input field. Please note it will be also translated, so check the translation file if your unit is already available. Add a new one if required.
### Smoothing control (only for effects)
Since v2 effects are no longer smoothed, it is possible to enable and manipulate smoothing if required. Add the following to the schema.
``` json
"smoothing-custom-settings":{
"type":"boolean",
"title":"edt_eff_smooth_custom",
"default":false,
"propertyOrder":1
},
"smoothing-time_ms":{
"type":"integer",
"title":"edt_eff_smooth_time_ms",
"minimum":25,
"maximum":600,
"default":200,
"append":"edt_append_ms",
"options":{
"dependencies":{
"smoothing-custom-settings":true
}
},
"propertyOrder":2
},
"smoothing-updateFrequency":{
"type":"number",
"title":"edt_eff_smooth_updateFrequency",
"minimum":1.0,
"maximum":100.0,
"default":25.0,
"append":"edt_append_hz",
"options":{
"dependencies":{
"smoothing-custom-settings":true
}
},
"propertyOrder":3
}
```
### Translation
**only for effects - plugins will follow** \
To translate the effect options to a language we use placeholders that are translated during runtime into the target language.
It will usually look like this
`edt_eff_smooth` Available phrases begins with `edt_eff_` they are shared across all effects to prevent duplicates. Please search the [translation file](https://github.com/hyperion-project/hyperion.ng/blob/master/assets/webconfig/i18n/en.json) for a matching translation. If you don't find a matching phrase please add it.

View File

@ -1,276 +0,0 @@
# Effect Engine API
All available functions for usage.
## API Overview
| Function | Returns | Comment |
| ------------------------------- | ----- | -------- |
| hyperion.ledCount | Integer | Get the current led count from the led layout |
| hyperion.latchTime | Integer | Get the current active latchtime in ms. |
| hyperion.imageWidth() | Integer | Get the current image width, calculate positions for elements at the [coordinate system](http://doc.qt.io/qt-5/coordsys.html#rendering) |
| hyperion.imageHeight() | Integer | Get the current image height,calculate positions for elements at the [coordinate system](http://doc.qt.io/qt-5/coordsys.html#rendering) |
| hyperion.imageCRotate() | - | Rotates the coordinate system at the center (0,0) by the given angle. See [hyperion.imageCRotate()](#hyperion-imagecrotate) |
| hyperion.imageCOffset() | - | Add a offset to the coordinate system. See [hyperion.imageCOffset()](#hyperion-imagecoffset) |
| hyperion.imageCShear() | - | Shear the coordinate system. See [hyperion.imageCShear()](#hyperion-imagecshear) |
| hyperion.imageResetT() | - | Resets all coordination system modifications done with hyperion.imageCRotate(), hyperion.imageCOffset(), hyperion.imageCShear() |
| hyperion.imageMinSize() | - | See [hyperion.imageMinSize()](#hyperion-imageminsize)|
| hyperion.abort() | Boolean | If true, hyperion requests an effect abort, used in a while loop to repeat effect calculations and writing |
| hyperion.imageConicalGradient() | - | See [hyperion.imageConicalGradient()](#hyperion-imageconicalgradient) |
| hyperion.imageRadialGradient() | - | See [hyperion.imageRadialGradient()](#hyperion-imageradialgradient)|
| hyperion.imageLinearGradient() | - | See [hyperion.imageLinearGradient()](#hyperion-imagelineargradient)|
| hyperion.imageDrawLine() | - | See [hyperion.imageDrawLine()](#hyperion-imagedrawline) |
| hyperion.imageDrawPoint() | - | See [hyperion.imageDrawPoint()](#hyperion-imagedrawpoint) |
| hyperion.imageDrawPolygon() | - | See [hyperion.imageDrawPolygon()](#hyperion-imagedrawpolygon) |
| hyperion.imageDrawPie() | - | See [hyperion.imageDrawPie()](#hyperion-imagedrawpie) |
| hyperion.imageDrawRect() | - | See [hyperion.imageDrawRect()](#hyperion-imagedrawrect) |
| hyperion.imageSolidFill() | - | See [hyperion.imageSolidFill()](#hyperion-imagesolidfill) |
| hyperion.imageShow() | - | Hyperion shows the image you created with other `hyperion.image*` functions before. This is always the last step after you created the image with other hyperion.image* function |
| hyperion.imageSetPixel() | - | See [hyperion.imageSetPixel()](#hyperion-imagesetpixel) |
| hyperion.imageGetPixel() | Tuple | A [Python tuple](https://www.tutorialspoint.com/python/python_tuples.htm) RGB values for the requested position. See [hyperion.imageGetPixel()](#hyperion-imagegetpixel) |
| hyperion.imageSave() | Integer | Create a snapshot of the current effect image and returns an ID. To display the snapshot do `hyperion.imageShow(ID)`. Snapshots are the _current_ state of the picture |
| hyperion.setColor() | - | Not recommended, read why! See [hyperion.setColor()](#hyperion-setcolor) |
| hyperion.setImage() | - | hyperion.setImage(width, height, RGB_bytearray) |
### hyperion.imageMinSize()
As the `hyperion.imageWidth()` and `hyperion.imageHeight()` scales with the led layout, you could define a minimum size to get more pixels to work with. Keep in mind that the ratio between width/height depends always on user led setup, you can't force it.
::: warning
Should be called before you start painting!
:::
`hyperion.imageMinSize(pixelX,pixelY)`
| Argument | Type | Comment |
| ---------- | -------- | ---------------------------------------------------------------------------------- |
| pixelX | Integer | Minimum Pixels at the x-axis of the image to draw on with `hyperion.image*` functions |
| pixelY | Integer | Minimum Pixels at the y-axis of the image to draw on with `hyperion.image*` functions |
### hyperion.imageCRotate()
Rotates the coordinate system at the center which is 0 at the x-axis and 0 at the y-axis by the given angle clockwise. Note: If you want to move the center of the coordinate system you could use hyperion.imageCOffset(). **The rotation is kept until the effect ends**. \
`hyperion.imageCRotate(angle)`
| Argument | Type | Comment |
| ---------- | -------- | ----------------------------------------------------- |
| angle | Integer | Angle of the rotation between `0` and `360`, clockwise |
### hyperion.imageCOffset()
Add offset to the coordinate system at the x-axis and y-axis.
::: warning
Changes at the coordinate system results in weird behavior of some shorter versions of other hyperion.image* drawing functions
:::
`hyperion.imageCOffset(offsetX, offsetY)`
| Argument | Type | Comment |
| -------- | ---------- | ----------------------------------------------------- |
| offsetX | Integer | Offset which is added to the coordinate system at the x-axis. Positive value moves to the right, negative to the left |
| offsetY | Integer | Offset which is added to the coordinate system at the y-axis. Positive value moves to the right, negative to the left |
### hyperion.imageCShear()
Shears the coordinate system at the vertical and horizontal. More info to shearing here: [Shear Mapping](https://en.wikipedia.org/wiki/Shear_mapping)
::: warning
Changes at the coordinate system results in weird behavior of some shorter versions of other hyperion.image* drawing functions
:::
`hyperion.imageCShear(sh, sv)`
| Argument | Type | Comment |
| -------- | ---------- | -------------------------- |
| sh | Integer | Horizontal pixels to shear |
| sv | Integer | Vertical pixels to shear. |
### hyperion.imageConicalGradient()
Draws a conical gradient on the image, all arguments are required. Add the arguments in the order of rows below. Short explanation for conical gradient at the QT docs: [Conical Gradient](http://doc.qt.io/qt-5/qconicalgradient.html#details) \
`hyperion.imageConicalGradient(startX, startY, width, height, centerX, centerY, angle, bytearray)`
| Argument | Type | Comment |
| -------- | ---------- | ----------------------------------------------------- |
| startX | Integer | Defines the start point at the x-axis of the rectangle that contains the gradient |
| startY | Integer | Defines the start point at the y-axis of the rectangle that contains the gradient |
| width | Integer | Defines the width of the rectangle |
| height | Integer | Defines the height of the rectangle |
| centerX | Integer | Defines the center of the gradient at the x-axis. For the center of the picture use `hyperion.imageWidth()*0.5`, don't forget to surround it with int() or round() |
| centerY | Integer | Defines the center of the gradient at the y-axis. For the center of the picture use `hyperion.imageHeight()*0.5`, don't forget to surround it with int() or round() |
| angle | Integer | Defines the angle from `0` to `360`. Used to rotate the gradient at the center point. |
| bytearray | ByteArray | bytearray of (position,red,green,blue,alpha,position,red,green,blue,alpha,...). Could be repeated as often you need it, all values have ranges from 0 to 255. The position is a point where the red green blue values are assigned. <br/> **Example:** `bytearray([0,255,0,0,255,255,0,255,0,255])` - this is a gradient which starts at 0 with color 255,0,0 and alpha 255 and ends at position 255 with color 0,255,0 and alpha 255. The colors in between are interpolation, so this example is a color shift from red to green from 0° to 360°. |
::: tip Shorter versions of hyperion.imageConicalGradient()
`hyperion.imageConicalGradient(centerX, centerY, angle, bytearray)` -> startX and startY are 0 and the width/height is max. -> Entire image
:::
### hyperion.imageRadialGradient()
Draws a radial gradient on the image. Add the arguments in the order of rows below. All arguments are required.
Short description at QT Docs: [Radial Gradient](http://doc.qt.io/qt-5/qradialgradient.html#details) \
`hyperion.imageRadialGradient(startX, startY, width, height, centerX, centerY, radius, focalX, focalY, focalRadius, bytearray, spread)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| startX | Integer | start point at the x-axis of the rectangle which contains the gradient. |
| startY | Integer | start point at the y-axis of the rectangle which contains the gradient. |
| width | Integer | width of the rectangle. |
| height | Integer | height of the rectangle. |
| centerX | Integer | Defines the center at the x-axis of the gradient. For the center of the picture use `hyperion.imageWidth()*0.5`, don't forget to surround it with int() or round() |
| centerY | Integer | Defines the center at the y-axis of the gradient. For the center of the picture use `hyperion.imageHeight()*0.5`, don't forget to surround it with int() or round() |
| radius | Integer | Defines the radius of the gradient in pixels |
| focalX | Integer | Defines the focal point at the x-axis |
| focalY | Integer | Defines the focal point at the y-axis |
|focalRadius| Integer | Defines the radius of the focal point |
| bytearray | ByteArray | bytearray of (position,red,green,blue,position,red,green,blue,...). Could be repeated as often you need it, all values have ranges from 0 to 255. The position is a point where the red green blue values are assigned <br/> **Example:** `bytearray([0,255,0,0,255,0,255,0])` - this is a gradient which starts at 0 with color 255,0,0 and ends at position 255 with color 0,255,0. The colors in between are interpolation, so this example is a color shift from red to green. |
| spread | Integer | Defines the spread method outside the gradient. Available spread modes are: <br/> `0` -> The area is filled with the closest stop color <br/> `1` -> The gradient is reflected outside the gradient area <br/> `2` -> The gradient is repeated outside the gradient area <br/> Please note that outside means _inside_ the rectangle but outside of the gradient start and end points, so if these points are the same, you don't see the spread mode. A picture to the spread modes can you find here: [Spread modes](http://doc.qt.io/qt-5/qradialgradient.html#details) |
::: tip Shorter versions of hyperion.imageRadialGradient()
- `hyperion.imageRadialGradient(startX, startY, width, height, centerX, centerY, radius, bytearray, spread)` -> focalX, focalY, focalRadius get their values from centerX, centerY and radius
- `hyperion.imageRadialGradient(centerX, centerY, radius, focalX, focalY, focalRadius, bytearray, spread)` -> startX and startY are 0
- `hyperion.imageRadialGradient(centerX, centerY, radius, bytearray, spread)` -> startX and startY are 0 & focalX, focalY, focalRadius get their values from centerX, centerY and radius
:::
### hyperion.imageLinearGradient()
Draws a linear gradient on the image. Add the arguments in the order of rows below. All arguments are required.
Short description at QT Docs: [Linear Gradient](http://doc.qt.io/qt-5/qlineargradient.html#details) \
`hyperion.imageLinearGradient(startRX, startRY, width, height, startX, startY, endX, endY, bytearray, spread)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| startRX | Integer | start point at the x-axis of the rectangle which contains the gradient. |
| startRY | Integer | start point at the y-axis of the rectangle which contains the gradient. |
| width | Integer | width of the rectangle. |
| height | Integer | height of the rectangle. |
| startX | Integer | Defines the start at the x-axis for the gradient. |
| startY | Integer | Defines the start at the y-axis for the gradient. |
| endX | Integer | Defines the end at the x-axis for the gradient. |
| endY | Integer | Defines the end at the y-axis for the gradient. |
| bytearray | ByteArray | bytearray of (position,red,green,blue,alpha,position,red,green,blue,alpha,...). Could be repeated as often you need it, all values have ranges from 0 to 255. The position is a point where the red green blue values are assigned. <br/> **Example:** `bytearray([0,255,0,0,255,255,0,255,0,127])` this is a gradient which starts at 0 with color 255,0,0 and alpha 255 and ends at position 255 with color 0,255,0 and alpha 127. The colors in between are interpolation, so this example is a color shift from red to green. |
| spread | Integer | Defines the spread method outside the gradient. Available spread modes are: <br/> `0` -> The area is filled with the closest stop color <br/> `1` -> The gradient is reflected outside the gradient area <br/> `2` -> The gradient is repeated outside the gradient area <br/> Please note that outside means _inside_ the rectangle but outside of the gradient start and end points, so if these points are the same, you don't see the spread mode. A picture to the spread modes can you find here: [Spread modes](http://doc.qt.io/qt-5/qlineargradient.html#details) |
::: tip Shorter versions of hyperion.imageLinearGradient()
`hyperion.imageLinearGradient(startX, startY, endX, endY, bytearray, spread)` -> The rectangle which contains the gradient defaults to the full image
:::
### hyperion.imageDrawLine()
Draws a line at the image. All arguments are required, exception a for alpha. Add the arguments in the order of rows below. \
`hyperion.imageDrawLine(startX, startY, endX, endY, thick, r, g, b, a)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| startX | Integer | start point at the x-axis. Relates to `hyperion.imageWidth()` |
| startY | Integer | start point at the y-axis. Relates to `hyperion.imageHeight()` |
| endX | Integer | end point at the x-axis. Relates to `hyperion.imageWidth()` |
| endY | Integer | end point at the y-axis. Relates to `hyperion.imageHeight()` |
| thick | Integer | Thickness of the line, should be calculated based on image height or width. But at least one Pixel. Example: `max(int(0.1*hyperion.imageHeight(),1)` is 10% of the image height. |
| r | Integer | red color from `0` to `255` |
| g | Integer | green color from `0` to `255` |
| b | Integer | blue color from `0` to `255` |
| a | Integer | **Optional** alpha of the color from `0` to `255`, if not provided, it's `255` |
::: tip Shorter versions of hyperion.imageLinearGradient()
`hyperion.imageLinearGradient(startX, startY, endX, endY, bytearray, spread)` -> The rectangle which contains the gradient defaults to the full image
:::
### hyperion.imageDrawPoint()
Draws a point/dot at the image. All arguments are required, exception a for alpha. Add the arguments in the order of rows below. \
`hyperion.imageDrawPoint(x, y, thick, r, g, b, a)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| x | Integer | point position at the x-axis. Relates to `hyperion.imageWidth()` |
| y | Integer | point position at the y-axis. Relates to `hyperion.imageHeight()` |
| thick | Integer | Thickness of the point in pixel, should be calculated based on image height or width. But at least one Pixel. Example: `max(int(0.1*hyperion.imageHeight(),1)` is 10% of the image height. |
| r | Integer | red color from `0` to `255` |
| g | Integer | green color from `0` to `255` |
| b | Integer | blue color from `0` to `255` |
| a | Integer | **Optional** alpha of the color from `0` to `255`, if not provided, it's `255` |
::: tip Shorter versions of hyperion.imageDrawPoint()
`hyperion.imageDrawPoint(x, y, thick, r, g, b)` -> alpha defaults to 255
:::
### hyperion.imageDrawPolygon()
Draws a polygon at the image and fills it with the specific color. Used for free forming (triangle, hexagon,... whatever you want ). All arguments are required, exception a for alpha. Add the arguments in the order of rows below. \
`hyperion.imageDrawPolygon(bytearray, r, g, b, a)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| bytearray | ByteArray | bytearray([point1X,point1Y,point2X,point2Y,point3X,point3Y,...]). Add pairs of X/Y coordinates to specific the corners of the polygon, each point has a X and a Y coordinate, you could add as much points as you need. The last point automatically connects to the first point.|
| r | Integer | red color from `0` to `255` |
| g | Integer | green color from `0` to `255` |
| b | Integer | blue color from `0` to `255` |
| a | Integer | **Optional** alpha of the color from `0` to `255`, if not provided, it's `255` |
::: tip Shorter versions of hyperion.imageDrawPolygon()
`hyperion.imageDrawPolygon(bytearray, r, g, b)` -> alpha defaults to 255
:::
### hyperion.imageDrawPie()
Draws a pie (also known from pie charts) at the image and fills it with the specific color. All arguments are required, exception a for alpha. Add the arguments in the order of rows below. \
`hyperion.imageDrawPie(centerX, centerY, radius, startAngle, spanAngle, r, g, b, a)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| centerX | Integer | The center of the Pie at the x-axis |
| centerY | Integer | The center of the Pie at the y-axis |
| radius | Integer | radius of the Pie in Pixels |
| startAngle| Integer | start angle from `0` to `360`. `0` is at 3 o'clock |
| spanAngle | Integer | span (wide) of the pie from `-360` to `360` which starts at the startAngle, positive values are counter-clockwise, negative clockwise |
| r | Integer | red color from `0` to `255` |
| g | Integer | green color from `0` to `255` |
| b | Integer | blue color from `0` to `255` |
| a | Integer | **Optional** alpha of the color from `0` to `255`, if not provided, it's `255` |
::: tip Shorter versions of hyperion.imageDrawPie()
`hyperion.imageDrawPie(centerX, centerY, radius, startAngle, spanAngle, r, g, b)` -> alpha defaults to 255
:::
### hyperion.imageDrawRect()
Draws a rectangle on the image. All arguments are required, exception a for alpha. Add the arguments in the order of rows below. \
`hyperion.imageDrawRect(startX, startY, width, height, thick, r, g, b, a,)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| startX | Integer | start point at the x-axis. Relates to `hyperion.imageWidth()` |
| startY | Integer | start point at the y-axis. Relates to `hyperion.imageHeight()` |
| width | Integer | width of the rectangle. Relates to `hyperion.imageWidth()` |
| height | Integer | height of the rectangle. Relates to `hyperion.imageHeight()` |
| thick | Integer | Thickness of the rectangle, a good start value is `1` |
| r | Integer | define red color from `0` to `255` |
| g | Integer | define green color from `0` to `255` |
| b | Integer | define blue color from `0` to `255` |
| a | Integer | **Optional** alpha of the color from `0` to `255`, if not provided, it's `255` |
### hyperion.imageSolidFill()
Fill a specific part of the image with a solid color (or entire). All arguments are required. Add the arguments in the order of rows below. \
`hyperion.imageSolidFill(startX, startY, width, height, r, g, b, a)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| startX | Integer | start point at the x-axis. Relates to `hyperion.imageWidth()` |
| startY | Integer | start point at the y-axis. Relates to `hyperion.imageHeight()` |
| width | Integer | width of the fill area. Relates to `hyperion.imageWidth()` |
| height | Integer | height of the fill area. Relates to `hyperion.imageHeight()` |
| r | Integer | define red color from `0` to `255` |
| g | Integer | define green color from `0` to `255` |
| b | Integer | define blue color from `0` to `255` |
| a | Integer | alpha of the color from `0` to `255` |
::: tip Shorter versions of hyperion.imageSolidFill()
- `hyperion.imageSolidFill(startX, startY, width, height, r, g, b)` -> no alpha, defaults to 255
- `hyperion.imageSolidFill(r, g, b, a)` -> startX and startY is 0, width and height is max. -> full image
- `hyperion.imageSolidFill(r, g, b)` -> startX and startY is 0, width and height is max, alpha 255. -> full image
:::
### hyperion.imageSetPixel()
Assign a color to a specific pixel position. All arguments are required. Add the arguments in the order of rows below. \
`hyperion.imageSetPixel(X, Y, r, g, b)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| X | Integer | pixel point at the x-axis. Relates to `hyperion.imageWidth()` |
| Y | Integer | pixel point at the y-axis. Relates to `hyperion.imageHeight()` |
| r | Integer | define red color from `0` to `255` |
| g | Integer | define green color from `0` to `255` |
| b | Integer | define blue color from `0` to `255` |
### hyperion.imageGetPixel()
Get a color of a specific pixel position. All arguments are required. Add the arguments in the order of rows below. \
`hyperion.imageGetPixel(X, Y)`
| Argument | Type | Comment |
| --------- | ---------- | ----------------------------------------------------- |
| X | Integer | pixel point at the x-axis. Relates to `hyperion.imageWidth()` |
| Y | Integer | pixel point at the y-axis. Relates to `hyperion.imageHeight()` |
| Return | Tuple | Returns a Python Tuple of RGB values |
### hyperion.setColor()
Set a single color to all leds by adding `hyperion.setColor(255,0,0)`, all leds will be red. But it is also possible to send a bytearray of RGB values. Each RGB value in this bytearray represents one led.
- **Example 1:** `hyperion.setColor(bytearray([255,0,0]))` The first led will be red
- **Example 2:** `hyperion.setColor(bytearray([255,0,0,0,255,0]))` The first led will be red, the second is green
- **Example 3:** `hyperion.setColor(bytearray([255,0,0,0,255,0,255,255,255]))` The first led will be red, the second is green, the third is white
- You usually assign to all leds a color, therefore you need to know how much leds the user currently have. Get it with `hyperion.ledCount`
::: warning hyperion.setColor()
- hyperion.setColor() function is not recommended to assign led colors, it doesn't work together with **`hyperion.image*`** functions
- You don't know where is top/left/right/bottom and it doesn't work with matrix layouts!
- Please consider to use the **`hyperion.image*`** functions instead to create amazing effects that scales with the user setup
:::

View File

@ -1,147 +0,0 @@
# Our first Effect
Let's create together our first effect! \
Target of this effect is to show the general structure of an effect, make you confident with the API and workflow.
## Requirements
* An installed and running Hyperion. You need access to the filesystem where Hyperion has been installed.
* Text editor (of your liking, i would recommend [Visual Studio Code](https://code.visualstudio.com/))
* Navigate to the "custom-effects" folder of your Hyperion installation (Inside .hyperion folder of your home directory)
* **Configure a led matrix layout at "LED Hardware"-section at the web configuration to 10x10 LEDs**
### Start
First, we start with the python file. Create a new file called `neweffect.py` in your `custom-effects` folder. \
We need to import some modules, `hyperion` and `time` is always required. The time module comes from Python, if you want to know, what methods such a module has, visit the [Python documentation](https://docs.python.org/3.5/library/). What `hyperion` can do, is already explained at [Effect Engine API](/en/effects/api.md).
``` python
# Let's import our modules, so we can use them
import hyperion, time
# Create a loop, this loop runs until the user stops the effect
while not hyperion.abort():
# Here we are inside the loop, let's do something
# According to the documentation of hyperion.imageDrawPoint()
# The position of this point is 2 at x-axis and 5 at the y-axis with a thickness of 1 pixel and color red
hyperion.imageDrawPoint(2,5,1,255,0,0)
# Now we need to tell Hyperion that we want to send the image we painted
hyperion.imageShow()
# As we are still in our loop let's have a break to slow down the execution. We should never waste CPU power :)
# Sleep a second until the loop starts from the beginning
time.sleep(1)
```
**Recap:**: First effect finished! We printed a red dot with a size of one pixel on an empty image and sent that to Hyperion.
### Configuration
Let's test our neweffect.py. Create a new file called `neweffect.json`. And place the following code inside
``` json
{
"name" : "My first own effect!",
"script" : "neweffect.py",
"args" : {
}
}
```
Let's talk about what we have done here
- The `neweffect.json` contains the configuration for our effect.
- The `name` property is the effect name which is displayed at the effect list and could be freely defined.
- The `script` property points to the python file it should start.
- The `args` property contains options and their values, for example a color, speed and so on. We leave this empty for the moment.
**After you added this file to your custom-effects folder, you need to restart Hyperion once**
Now you should see the "My first own effect!" effect at the remote page effect list. Start the effect, you should see something like this at led visualization.
<ImageWrap src="/images/en/owneff_1.jpg" alt="Custom Hyperion Effect" />
According to the [coordinate system](http://doc.qt.io/qt-5/coordsys.html#rendering), we are at 2 at the x-axis and 5 at the y-axis like written before. Perfect!
### Add color option
Now we want to make the color of the dot configurable. \
Let's edit the neweffect.py.
``` python
import hyperion, time
# Let's get the value of option custom-color, values will be saved in the color variable
color = hyperion.args.get('custom-color', (0,255,200))
while not hyperion.abort():
# Get the color information from the variable color
hyperion.imageDrawPoint(2,5,1,color[0],color[1],color[2])
hyperion.imageShow()
time.sleep(1)
```
* With `hyperion.args.get()` we grab the values from the neweffect.json that starts this python file (from the `args` property of the neweffect.json, which is currently empty.).
* The color array at the end of `hyperion.args.get('custom-color', (0,255,200))` is a fallback value as we don't deliver a `custom-color` property inside the args of the neweffect.json. This ensures always a working effect, choose these default values wisely.
* As you see the `hyperion.imageDrawPoint(...)` got also a modification, as we write the `custom-color` into the variable `color` we access the values with `color[0]` which is 0, `color[1]` which is 255 and `color[2]` which is 200.
**Save the neweffect.py and restart the effect, a restart of Hyperion is not required** \
It should now look like this
<ImageWrap src="/images/en/owneff_2.jpg" alt="Custom Hyperion Effect with cyan color" />
### More dots!
Now we have a single dot, and we prepared the color for the dot to be configurable. Now we want more of them! \
Again we edit the neweffect.py
``` python
import hyperion, time, random
color = hyperion.args.get('custom-color', (0,255,200))
iWidth = hyperion.imageWidth()
iHeight = hyperion.imageHeight()
while not hyperion.abort():
hyperion.imageDrawPoint(random.randint(0,iWidth),random.randint(0,iHeight),1,color[0],color[1],color[2])
hyperion.imageShow()
time.sleep(1)
```
* We grab now the width (`hyperion.imageWidth()`) and height (`hyperion.imageHeight()`) of the image to make sure that we can fill the entire image with dots. For the required randomness we [import random](https://docs.python.org/3.5/library/random.html) and use `random.randint()` with a minimum value of 0 and a maximum value of our width and height. This creates random integer numbers.
* Keep in mind that the user setup has always a different width, height and even the ratio between them is dynamic based on the led layout.
* **Never use fixed positions, thickness,... calculate them always!**
So this is the image when we run the effect again.
<ImageWrap src="/images/en/owneff_3.gif" alt="Custom Hyperion Effect with random dots" />
Each second (remember the `sleep.time(1)`) it paints at a random position a new dot, endless. It doesn't check if there is already a dot, it just overwrites the old dot.
### More color
Let's add an option which force the effect to paint optional a random color for each dot instead always the same. \
Again we edit the neweffect.py
``` python
import hyperion, time, random
# a helper function to convert HSV to RGB space
def hsv_to_rgb(h, s, v):
if s == 0.0: v*=255; return [v, v, v]
i = int(h*6.)
f = (h*6.)-i; p,q,t = int(255*(v*(1.-s))), int(255*(v*(1.-s*f))), int(255*(v*(1.-s*(1.-f)))); v*=255; i%=6
if i == 0: return [v, t, p]
if i == 1: return [q, v, p]
if i == 2: return [p, v, t]
if i == 3: return [p, q, v]
if i == 4: return [t, p, v]
if i == 5: return [v, p, q]
color = hyperion.args.get('custom-color', (0,255,200))
randomColor = bool(hyperion.args.get('random-color', True))
iWidth = hyperion.imageWidth()
iHeight = hyperion.imageHeight()
while not hyperion.abort():
if randomColor:
color = hsv_to_rgb(random.uniform(0,1), 1, 1)
hyperion.imageDrawPoint(random.randint(0,iWidth),random.randint(0,iHeight),1,color[0],color[1],color[2])
hyperion.imageShow()
time.sleep(1)
```
* To generate bright colors we write our own function: `def hsv_to_rgb(h, s, v): ...`
* So we add also a new option `randomColor` which is True, we parse True/False values always as `bool(...)` to make sure they are really bool, and not a string. If you don't know what's the difference between a bool, string, int and float is, do a short browse at the [python documentation](https://docs.python.org/3.5/library/stdtypes.html).
* Inside our `while not hyperion.abort():` loop we check with `if randomColor:` if randomColor is true or not, if it is true (enabled) we overwrite our variable `color` with a random color that is generated with `hsv_to_rgb(h,s,v)`. We just randomize h for Hue with our random function `hsv_to_rgb(random.uniform(0,1), 1, 1)`, the h accepts values between 0 and 1. What is hue? Play around with hue at [this](https://www.w3schools.com/colors/colors_hsl.asp) colorpicker. You see why this is a easy way to generate bright colors with a simple random function.
**Save the file and restart the effect**
<ImageWrap src="/images/en/owneff_4.gif" alt="Custom Hyperion Effect with random dots and color" />
### Clear the image
Let's add a option to set the image to black on a configurable interval in seconds. This overwrites all dots with black.
::: tip
I am sorry, more will come soon
:::

View File

@ -1,12 +0,0 @@
# Effect development
Hyperion provides a powerful API to write your own effects, along with possible options and user interface to tune them.
[[toc]]
## Effect Files
An effect has 3 different files.
| File | language | Comment |
| :-------------------: | :-----------------------------------: | :-----------------------------------------------------------------------------------: |
| neweffect.py | [Python](https://www.python.org) | The heart of the effect |
| neweffect.json | [JSON](http://www.json.org) | Contains options for the python file, which makes it configurable |
| neweffect.schema.json | [JSON Schema](http://json-schema.org) | Creates the options UI and is used to validate user input. [Read more](/en/api/ui.md) |

View File

@ -1,164 +0,0 @@
## Authorization
Hyperion has an authorization system allowing users to login via password, and
applications to login with tokens. The user can configure how strong or weak the Hyperion API
should be protected from the `Configuration` -> `Network Services` panel on the Web UI.
[[toc]]
### Token System
Tokens are a simple way to authenticate an App for API access. They can be created in
the UI on the `Configuration` -> `Network Services` panel (the panel appears when `API
Authentication` options is checked). Your application can also [request a
token](#request-a-token) via the API.
### Authorization Check
Callers can check whether authorization is required to work with the API, by sending:
```json
{
"command" : "authorize",
"subcommand" : "tokenRequired"
}
```
If the property `required` is true, authentication is required. An example response:
```json
{
"command" : "authorize-tokenRequired",
"info" : {
"required" : true
},
"success" : true,
"tan" :0
}
```
### Login with Token
Login with a token as follows -- the caller will receive a [Login response](#login-response).
```json
{
"command" : "authorize",
"subcommand" : "login",
"token" : "YourPrivateTokenHere"
}
```
### Login with Token over HTTP/S
Add the HTTP Authorization header to every request. On error, the user will get a failed [Login response](#login-response).
```http
Authorization : token YourPrivateTokenHere
```
#### Login response
A successful login response:
```json
{
"command" : "authorize-login",
"success" : true,
"tan" : 0
}
```
A failed login response:
```json
{
"command" : "authorize-login",
"error" : "No Authorization",
"success" : false,
"tan" : 0
}
```
### Logout
Users can also logout. Hyperion doesn't verify the login state, this call will always
return a success.
```json
{
"command" : "authorize",
"subcommand" : "logout"
}
```
Response:
```json
{
"command" : "authorize-logout",
"success" : true,
"tan" : 0
}
```
::: warning
Logging out will stop all streaming data services and subscriptions
:::
### Request a Token
Here is the recommended workflow for your application to authenticate:
* Ask Hyperion for a token along with a comment (a short meaningful string that
identifies the caller is the most useful, e.g. includes an application name and
device) and a short randomly created `id` (numbers/letters).
* Wait for the response. The user will need to accept the token request from the Web UI.
* On success: The call will return a UUID token that can be repeatedly used. Note that
access could be revoked by the user at any time, but will continue to last for
currently connected sessions in this case.
* On error: The call won't get a token, which means the user either denied the request or it timed out (180s).
Request a token using the follow command, being sure to add a comment that is
descriptive enough for the Web UI user to make a decision as to whether to grant or deny
the request. The `id` field has 5 random chars created by the caller, which will appear
in the Web UI as the user considers granting their approval.
```json
{
"command" : "authorize",
"subcommand" : "requestToken",
"comment" : "OpenHab 2 Binding",
"id" : "T3c91"
}
```
After the call, a popup will appear in the Web UI to accept/reject the token request.
The calling application should show the comment and the id so that the user can confirm
the origin properly in the Hyperion UI. After 180 seconds without a user action, the
request is automatically rejected, and the caller will get a failure response (see below).
#### Success response
If the user accepted the token request the caller will get the following response:
```json
{
"command" : "authorize-requestToken",
"success" : true,
"info": {
"comment" : "OpenHab2 Binding",
"id" : "T3c91",
"token" : "YourPrivateTokenHere"
}
}
```
* Save the token somewhere for further use. The token does not expire.
* Be aware that a user can revoke the token. It will continue to function for currently connected sessions.
#### Failed response
A request will fail when either:
* It times out (i.e. user neither approves nor rejects for 180 seconds after the request
is sent).
* User rejects the request.
```json
{
"command" : "authorize-requestToken",
"success" : false,
"error" : "Token request timeout or denied"
}
```
#### Request abort
You can abort the token request by adding an "accept" property to the original request.
The request will be deleted:
```json
{
"command" : "authorize",
"subcommand" : "requestToken",
"comment" : "OpenHab 2 Binding",
"id" : "T3c91",
"accept" : false
}
```

View File

@ -1,385 +0,0 @@
# Control
You can control Hyperion by sending specific JSON messages.
::: tip
The `tan` property is supported in these calls, but omitted for brevity.
:::
[[toc]]
## Sections
### Set Color
Set a color for all leds or provide a pattern of led colors.
| Property | Type | Required | Comment |
| :------: | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------: |
| color | Array | true | An array of R G B Integer values e.g. `[R,G,B]` |
| duration | Integer | false | Duration of color in ms. If you don't provide a duration, it's `0` -> indefinite |
| priority | Integer | true | We recommend `50`, following the [Priority Guidelines](/en/api/guidelines#priority_guidelines). Min `2` Max `99` |
| origin | String | true | A short name of your application like `Hyperion of App` . Max length is `20`, min `4`. |
```json
// Example: Set a blue color with indefinite duration at priority 50
{
"command":"color",
"color":[0,0,255],
"priority":50,
"origin":"My Fancy App"
}
// Example: Set a cyan color for 12 seconds at priority 20
{
"command":"color",
"color":[0,255,255],
"duration":12000,
"priority":20,
"origin":"My Fancy App"
}
// Example: Provide a color pattern, which will be repeated until all LEDs have a color
// In this case LED 1: Red, LED 2: Red, LED 3: Blue.
{
"command":"color",
"color":[255,0,0,255,0,0,0,0,255], // one led has 3 values (Red,Green,Blue) with range of 0-255
"duration":12000,
"priority":20,
"origin":"My Fancy App"
}
```
### Set Effect
Set an effect by name. Available names can be found in the [serverinfo effect list](/en/json/ServerInfo.md#effect-list).
| Property | Type | Required | Comment |
| :------: | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------: |
| effect | Object | true | Object with additional properties. e.g. `"name":"EffectName"`. |
| duration | Integer | false | Duration of effect in ms. If you don't provide a duration, it's `0` -> indefinite |
| priority | Integer | true | We recommend `50`, following the [Priority Guidelines](/en/api/guidelines#priority_guidelines). Min `2` Max `99` |
| origin | String | true | A short name of your application like `Hyperion of App` . Max length is `20`, min `4`. |
```json
// Example: Set the 'Warm mood blobs' effect with indefinite duration
{
"command":"effect",
"effect":{
"name":"Warm mood blobs"
},
"priority":50,
"origin":"My Fancy App"
}
// Example: Set 'Rainbow swirl' effect for 5 seconds
{
"command":"effect",
"effect":{
"name":"Rainbow swirl"
},
"duration":5000,
"priority":50,
"origin":"My Fancy App"
}
// Example: Set 'Rainbow swirl' effect for 1 second with overridden agrument
// Each effect has different agruments inside the args property that can be overridden.
// WARNING: We highly recommend using the effects configurator in the UI instead. Sending invalid values may cause the effect to misbehave or crash.
{
"command":"effect",
"effect":{
"name":"Rainbow swirl",
"args":{
"rotation-time":1
}
},
"duration":5000,
"priority":50,
"origin":"My Fancy App"}
```
### Set Image
Set a single image. Supports all [Qt5](https://doc.qt.io/qt-5/qimagereader.html#supportedImageFormats) image formats, including png/jpg/gif.
| Property | Type | Required | Comment |
| :-------: | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------: |
| imagedata | String | true | Data of image as [Base64](https://en.wikipedia.org/wiki/Base64) |
| format | String | true | Set to `auto` to let Hyperion parse the image according to type |
| name | String | true | The name of the image |
| duration | Integer | false | Duration of image in ms. If you don't provide a duration, it's `0` -> endless |
| priority | Integer | true | We recommend `50`, following the [Priority Guidelines](/en/api/guidelines#priority_guidelines). Min `2` Max `99` |
| origin | String | true | A short name of your application like `Hyperion of App` . Max length is `20`, min `4`. |
```json
// Set an image for 5 seconds
{
"command":"image",
"imagedata":"VGhpcyBpcyBubyBpbWFnZSEgOik=", // as base64!
"name":"Name of Image",
"format":"auto",
"priority":50,
"duration":5000,
"origin": "My Fancy App"
}
```
### Clear
Clear a priority, usually used to revert [set color](#set-color), [set
effect](#set-effect) or [set image](#set-image).
```json
// Clear effect/color/image with priority 50
{
"command":"clear",
"priority":50,
}
// Clear all effects/colors/images
{
"command":"clear",
"priority":-1,
}
```
::: warning
When you clear all, you clear all effects and colors regardless of who set them!
Instead, we recommend users provide a list of possible clear targets based on a
priority list
:::
### Adjustments
Adjustments reflect the color calibration. You can modify all properties of [serverinfo adjustments](/en/json/serverinfo#adjustments).
| Property | Type | Required | Comment |
| :--------------------: | :------------: | :------: | :--------------------------------------------------------------------------------------------: |
| red | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| green | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| blue | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| cyan | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| magenta | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| yellow | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| white | Array | false | An array of R G B Integer values e.g. `[R,G,B]` |
| gammaRed | Number (float) | false | minimum:`0.1` maximum `5.0` step of `0.1` |
| gammaGreen | Number (float) | false | minimum:`0.1` maximum `5.0` step of `0.1` |
| gammaBlue | Number (float) | false | minimum:`0.1` maximum `5.0` step of `0.1` |
| brightness | Integer | false | minimum: `0` maximum `100` step of `1` |
| brightnessCompensation | Integer | false | minimum: `0` maximum `100` step of `1` |
| backlightThreshold | Integer | false | minimum: `0` maximum `100`. Step of `1`. (Minimum brightness!) Disabled for effect/color/image |
| backlightColored | Boolean | false | If `true` the backlight is colored, `false` it's white. Disabled for effect/color/image |
| id | String | false | Short identifier |
```json
// Example: Set gammaRed to 1.5
{
"command":"adjustment",
"adjustment":{
"gammaRed":1.5
}
}
// Example: Set green to [0,236,0]
{
"command":"adjustment",
"adjustment":{
"green":[0,236,0]
}
}
// Example: Set backlightColored to true
{
"command":"adjustment",
"adjustment":{
"backlightColored":true
}
}
// Example: Send the 3 examples above at once
{
"command":"adjustment",
"adjustment":{
"backlightColored":true,
"gammaRed":1.5,
"green":[0,236,0]
}
}
```
### LED mapping
Switch the image to led mapping mode. Possible values are `unicolor_mean` (led color based on whole picture color) and `multicolor_mean` (led colors based on led layout)
```json
// Example: Set mapping mode to multicolor_mean
{
"command":"processing",
"mappingType":"multicolor_mean"
}
// Example: Set mapping mode to unicolor_mean
{
"command":"processing",
"mappingType":"unicolor_mean"
}
```
### Video Mode
Switch the video mode. Possible values are: `2D`, `3DSBS` and `3DTAB`.
```json
// Example: Set video mode to 3DTAB
{
"command":"videomode",
"videoMode":"3DTAB"
}
// Example: Set video mode to 3DSBS
{
"command":"videomode",
"videoMode":"3DSBS"
}
```
### Control Components
Some components can be enabled and disabled at runtime. To get the current state and
available components see [Serverinfo Components](/en/json/serverinfo#components). See
also: [Components/IDs explained](#components-ids-explained)
```json
// Example: disable LEDDEVICE component
{
"command":"componentstate",
"componentstate":{
"component":"LEDDEVICE",
"state":false
}
}
// Example: enable SMOOTHING component
{
"command":"componentstate",
"componentstate":{
"component":"SMOOTHING",
"state":true
}
}
```
::: warning
Hyperion itself needs to be enabled! Check the status of "ALL" in the components list before you change another component!
:::
### Components/IDs explained
Each component has a unique id. Not all of them can be enabled/disabled -- some of them,
such as effect and color, are used to determine the source type when examining the
[priority list](/en/json/ServerInfo.html#priorities).
| ComponentID | Component | Enable/Disable | Comment |
| :------------: | :------------------: | :------------: | :---------------------------------------------------------------------------: |
| SMOOTHING | Smoothing | Yes | Smoothing component |
| BLACKBORDER | Blackborder detector | Yes | Black bar detection component |
| FORWARDER | Json/Proto forwarder | Yes | Json/Proto forwarder component |
| BOBLIGHTSERVER | Boblight server | Yes | Boblight server component |
| GRABBER | Platform capture | Yes | Platform Capture component |
| V4L | V4L capture device | Yes | USB capture device component |
| LEDDEVICE | Led device | Yes | Led device component start/stops output of the configured led device |
| ALL | SPECIAL: Hyperion | Yes | Enable or disable Hyperion. Recovers/saves last state of all other components |
| COLOR | Solid color | No | All colors that has been set belongs to this component |
| EFFECT | Effect | No | All effects belongs to this component |
| IMAGE | Solid Image | No | All single/solid images belongs to this. NOT for streaming |
| FLATBUFSERVER | Flatbuffers Server | No | All image stream sources from flatbuffer server |
| PROTOSERVER | Protobuffer Server | No | All image stream sources from Protobuffer server |
### Source Selection
Sources are always selected automatically by priority value (lowest value is the highest
priority). You need to know the priority value of the source you want to select -- these
priority values are available in the [serverinfo
Priorities](/en/json/serverinfo#priorities).
```json
// Example: Set priority 50 to visible
{
"command":"sourceselect",
"priority":50
}
```
If you get a success response, the `priorities_autoselect`-status will switch to false (see [serverinfo Autoselection Mode](/en/json/serverinfo##priorities-selection-auto-manual)). You are now in manual mode, to switch back to auto mode send:
```json
{
"command":"sourceselect",
"auto":true
}
```
After which, the `priorities_autoselect`-status will return to `true`.
::: warning
You can only select priorities which are `active:true`!
:::
### Control Instances
An instance represents an LED hardware instance. It runs within its own scope with it's
own plugin settings, led layout and calibration. Before selecting you can instance, you
should first get information about the available instances from [serverinfo](/en/json/serverinfo#instance).
```json
// Command to start instance 1
{
"command" : "instance",
"subcommand" : "startInstance",
"instance" : 1
}
// Command to stop instance 1
{
"command" : "instance",
"subcommand" : "stopInstance",
"instance" : 1
}
```
### API Instance handling
On connection to the API you will be connected to instance `0` by default. You can
control only one instance at the same time within a single connection, and
[subscriptions](/en/json/subscribe#instance-updates) are in the context of the selected instance.
It's possible to switch to another instance with the following command:
```json
// Switch to instance 1
{
"command" : "instance",
"subcommand" : "switchTo",
"instance" : 1
}
```
This will return a success response or an error if the instance isn't available.
::: warning
It's possible that an instance will stop while you are connected to it. In this case
connections on that instance will automatically be reset to instance `0`. Keep watching
the instance data via subscription if you need to handle this case.
See: [Instance updates](/en/json/subscribe#instance-updates).
:::
### Live Image Stream
You can request a live image stream (if the current source priority supports it,
otherwise here may be no response).
```json
{
"command":"ledcolors",
"subcommand":"imagestream-start"
}
```
You will receive "ledcolors-imagestream-update" messages with a base64 encoded image.
Stop the stream by sending:
```json
{
"command":"ledcolors",
"subcommand":"imagestream-stop"
}
```
::: danger HTTP/S
This feature is not available for HTTP/S JSON-RPC
:::
### Live Led Color Stream
You can request a live led color stream with current color values in RGB for each single
led. The update rate is 125ms.
```json
{
"command":"ledcolors",
"subcommand":"ledstream-start"
}
```
You will receive "ledcolors-ledstream-update" messages with an array of all led colors.
Stop the stream by sending:
```json
{
"command":"ledcolors",
"subcommand":"ledstream-stop"
}
```
::: danger HTTP/S
This feature is not available for HTTP/S JSON-RPC
:::

View File

@ -1,96 +0,0 @@
# JSON RPC Introduction
The JSON-RPC interfaces provides many ways to interact with Hyperion. You can retrieve
information about your server, your instances and take actions (such as setting a
priority input).
[[toc]]
## What is JSON?
JSON is a standardized message format (see [JSON.org](http://www.json.org/)) and is supported
by most programming languages. It is human readable which makes for easier debugging.
### Sending JSON
Hyperion requires a specially formatted JSON message. A `command` argument is always
required. A `tan` argument is optional. This is an integer you can freely choose -- it is
part of the response you will receive to allow you to filter the response from other server
messages (this functionality is likely necessary for advanced usecases only).
```json
{
"command" : "YourCommand",
"tan" : 1
}
```
Depending on the command, there might be an additional subcommand required:
```json
{
"command" : "YourCommand",
"subcommand" : "YourSubCommand",
"tan" : 1
}
```
### Response
Most messages you send will trigger a response of the following format:
```json
{
"command" : "YourCommand",
"info":{ ...DATA... },
"success" : true,
"tan" : 1
}
```
- **command**: The command you requested.
- **tan**: The tan you provided (If not, it will default to 0 in the response).
- **success**: true or false. If false, an **error** argument will contain details of the issue.
- **info**: The data you requested (if any).
## Connect
Hyperion currently supports multiple connection mechanisms: TCP Socket ("Json Server"), WebSocket and HTTP/S.
::: tip
You can automatically discover Hyperion servers! See [Detect Hyperion](/en/api/detect.md)
:::
### TCP Socket
This is a "raw" connection, you can send and receive line-separated json from the server
(default port: 19444). This is also known as the "Json Server".
### WebSocket
This is part of the Hyperion webserver (default port: 8090). You send and receive json
commands. WSS is also supported on port 8092. Only TEXT mode is supported. Read more
about websockets at [Websocket](https://en.wikipedia.org/wiki/WebSocket|).
### HTTP/S Json
HTTP requests can also be sent to the webserver (default port: 8090, for HTTPS: 8092). Send a HTTP/S POST request along with a properly formatted json message in the body to the (example) url: `http://IpOfDevice:WebserverPort/json-rpc`
<ImageWrap src="/images/en/http_jsonrpc.jpg" alt="Control Hyperion with HTTP JSON RPC">
Example picture with a [Firefox](https://addons.mozilla.org/de/firefox/addon/restclient/)/[Chrome](https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related) Addon to send HTTP JSON messages
</ImageWrap>
::: tip
If you get a "No Authorization" response, you need to create an [Authorization Token](/en/json/Authorization.md#token-system)
:::
::: warning HTTP/S Restrictions
Please note that the HTTP JSON-RPC lacks of the following functions due to technical limitations.
- Image streams, led color streams, logging streams, subscriptions
:::
## API
### Server Info
A large variety of data is available from the server: [Server Info](/en/json/ServerInfo.md)
### Control
Control your Hyperion server: [Control](/en/json/Control.md)
### Authorization
Authorization mechanisms: [Authorization](/en/json/Authorization.md)
### Subscribe
Data subscriptions: [Subscribe](/en/json/Subscribe.md)
## 3rd Party Libraries
* [Hyperion-py](https://github.com/dermotduffy/hyperion-py) is a 3rd-party Python
library for communication with Hyperion-NG. It uses the API described here as the
underlying communication mechanism and presents it in a user-friendly way. As a 3rd
party library, it is not supported by the Hyperion development team.

View File

@ -1,322 +0,0 @@
# Server Information
This is the primary read mechanism of the Hyperion server. This single command provides data about the live state of Hyperion, broken down into a number
of different parts (described below).
[[toc]]
You can request a `serverinfo` response by sending the following command:
```json
{
"command":"serverinfo",
"tan":1
}
```
## Parts of a serverinfo response
### Components
List of Hyperion components and their current status "enabled" (on/off). You can enable
or disable them during runtime . The "ALL" component reflect Hyperion as a whole -- if
"ALL" is false (off) you can't enable any other component. [See control
components](/en/json/control#control-components)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Component updates](/en/json/subscribe#component-updates)
:::
```json
{
"components":[
{
"enabled":true,
"name":"ALL"
},
{
"enabled":true,
"name":"SMOOTHING"
},
{
"enabled":true,
"name":"BLACKBORDER"
},
{
"enabled":false,
"name":"FORWARDER"
},
{
"enabled":false,
"name":"BOBLIGHTSERVER"
},
{
"enabled":false,
"name":"GRABBER"
},
{
"enabled":false,
"name":"V4L"
},
{
"enabled":true,
"name":"LEDDEVICE"
}
]
}
```
### Adjustments
Adjustments reflect the value of the last performed (non-persistent) color adjustment
(e.g. brightness). Read more about [control Adjustments](/en/json/control#adjustments)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Adjustment updates](/en/json/subscribe#adjustment-updates)
:::
```json
{
"adjustment":[
{
"backlightColored":true,
"backlightThreshold":0,
"blue":[0,0,255],
"brightness":1,
"cyan":[0,127,127],
"gammaBlue":1.4,
"gammaGreen":1.4,
"gammaRed":1.4,
"green":[0,255,0],
"id":"default",
"magenta":[255,0,255],
"red":[255,0,0],
"white":[255,255,255],
"yellow":[255,255,0]
}
]
}
```
### Effect list
An array of effects where each object is one named effect. You can filter between user
created effects and system provided effects by checking the effect `file` string -- if
it begins with `:` it's a system provided effect, whereas if the path begins with `/`,
it's a user created effect.
See also [set Effect](/en/json/control#set-effect)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Effect updates](/en/json/subscribe#effects-updates)
:::
```json
{
"effects":[
{
"args":{
"blobs":5,
"color":[
0,
0,
255
],
"hueChange":60,
"reverse":false,
"rotationTime":60
},
"file":":/effects//mood-blobs-blue.json",
"name":"Blue mood blobs",
"script":":/effects//mood-blobs.py"
},
{
"args":{
"brightness":100,
"candles":"all",
"color":[
255,
138,
0
],
"sleepTime":0.14999999999999999
},
"file":":/effects//candle.json",
"name":"Candle",
"script":":/effects//candle.py"
}
....
]
}
```
### LED mapping
Active mode of the led area mapping. [See control LED mapping](/en/json/control#led-mapping)
::: tip Subscribe
You can subscribe to future data updates. Read more about [LED mapping updates](/en/json/subscribe#led-mapping-updates)
:::
```json
"imageToLedMappingType":"multicolor_mean"
```
### Video mode
The current video mode of grabbers. Can be switched to 3DHSBS, 3DVSBS. [See control video mode](/en/json/control#video-mode)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Video mode updates](/en/json/subscribe#videomode-updates)
:::
```json
"videomode" : "2D"
```
### Priorities
Overview of the registered/active sources. Each object is a source.
* **active**: If "true" it is selectable for manual source selection. [See also source selection](/en/json/control#source-selection)
* **visible**: If "true" this source is displayed and pushed to the led device. The `visible:true`-source is always the first entry!
* **componentId**: A key belonging to a specific component that indicates the kind of input. [See available components](/en/json/control#components-ids-explained)
* **origin**: A named external setter of this source for reference purposes. If not given it's `System` (from Hyperion).
* **owner**: Contains additional information related to the componentId. If it's an effect,
the effect name is shown here. If it's USB capture, the capture device is shown. If
it's platform capture, you get the name of the platform capture implementation (e.g. dispmanx/x11/amlogic/...).
* **priority**: The priority of this source, an integer between 0 and 255.
* **value**: If the source is a color AND color data is available (if active is false
there's usually no datta),hen this will be the color in RGB and HSL.
* **duration_ms**: Actual duration in ms until this priority is automatically deleted.
This is shown if source is color or effect AND a specific duration higher than
`0` is set (0 means indefinite).
::: tip Subscribe
You can subscribe to future data updates. Read more about [Priority updates](/en/json/subscribe#priority-updates)
:::
```json
"priorities":[
{
"active":true,
"componentId":"COLOR",
"origin":"Web Configuration@192.168.0.28",
"owner":"COLOR",
"priority":1,
"value":{
"HSL":[
0,
1,
0.50000762939453125
],
"RGB":[
0,
0,
255
]
},
"visible":true
},
{
"active":true,
"componentId":"EFFECT",
"origin":"System",
"owner":"Warm mood blobs",
"priority":255,
"visible":false
}
]
```
### Priorities selection: Auto/Manual
If `priorities_autoselect` is "true" the visible source is determined by priority. The
lowest number is automatically selected. If a caller requests to set a source manually,
then `priorities_autoselect` switches to `false`.
If the manually selected source is cleared/stops/completes-duration OR the user requests
the auto selection, `priorities_autoselect` switches back to `true`. This value is
atomically updated with the priority updates (shown above).
[See also source selection](/en/json/control#source-selection).
### Instance
Information about available instances and their state. Each instance represents a LED
device. Instances can be controlled, see: [Control Instance](/en/json/control#control-instances).
::: tip Subscribe
You can subscribe to future data updates. Read more about [Instance Updates](/en/json/subscribe#instance-updates)
:::
```json
"instance":[
{
"instance": 0,
"running" : true,
"friendly_name" : "My First LED Hardware instance"
},
{
"instance": 1,
"running" : false,
"friendly_name" : "PhilipsHue LED Hardware instance"
}
]
```
### LEDs
Information about led layout (image mapping positions) and led count.
::: tip Subscribe
You can subscribe to future data updates. Read more about [LEDs Updates](/en/json/subscribe#leds-updates)
:::
```json
{
"leds":[
{
"hmin":0.0,
"hmax":1.0,
"vmin":0.0,
"vmax":1.0
},
{
"hmin":0.0,
"hmax":1.0,
"vmin":0.0,
"vmax":1.0
},
...
]
}
```
### System & Hyperion
It's possible to retrieve basic system information about the Hyperion server and the
host it runs on. This information is static and won't change during runtime.
```json
{
"command" : "sysinfo",
"tan" : 1
}
```
You can use the "version" (Hyperion version) string to check application compatibility. We use [Semantic Versioning 2.0.0](https://semver.org/).
If you need a specific id to re-detect known servers you can use the `id` field which
provides a unique id and will not change for a given server.
```json
{
"hyperion":{
"build":"webd (brindosch-38f97dc/814977d-1489698970)",
"gitremote": "https://github.com/hyperion-project/hyperion.git",
"time":"Mar 16 2017 21:25:46",
"version":"2.0.0",
"id":"jKsh78D3hd..."
},
"system":{
"architecture":"arm",
"hostName":"raspberrypi",
"kernelType":"linux",
"kernelVersion":"4.4.13-v7+",
"prettyName":"Raspbian GNU/Linux 8 (jessie)",
"productType":"raspbian",
"productVersion":"8",
"wordSize":"32"
}
}
```
### Sessions
`sessions` shows all Hyperion servers on the current network found via Zeroconf/avahi/bonjour. See also [detect Hyperion](/en/api/detect.md)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Session updates](/en/json/subscribe#session-updates)
:::
```json
{
"sessions":[
{
"address":"192.168.0.20",
"domain":"local.",
"host":"raspberrypi",
"name":"Awwh yeah!!@raspberrypi:8099",
"port":8090,
"type":"_hyperiond-http._tcp."
}
]
}
```

View File

@ -1,305 +0,0 @@
# Subscription
During a `serverinfo` request the caller can optionally subscribe to updates -- either
to specific [serverinfo parts](/en/json/ServerInfo.html#parts) or all available data.
These updates will be pushed whenever a server-side data change occurs, without the need
for the caller to poll.
[[toc]]
To subscribe to specific updates, you can modify the serverinfo command to:
```json
{
"command":"serverinfo",
"subscribe":[
"firstCommand",
"secondCommand",
"thirdCommand"
],
"tan":1
}
```
To subscribe for all available updates modify the severinfo command to
```json
{
"command":"serverinfo",
"subscribe":["all"],
"tan":1
}
```
### Base response layout
All pushed subscription updates will have an `-update` suffix added to the relevant key
from the [serverinfo part in question](/en/json/ServerInfo.html#parts). The new data
will be in the `data` property. There is no `tan` nor `success` argument provided.
```json
{
"command":"XYZ-update",
"data":{
..Data here..
}
}
```
### Component updates
The caller can subscribe to component updates. These updates are meant to update the
`components` section of the caller's initial serverinfo. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":[
"components-update"
],
"tan":1
}
```
After this, the caller will receive incremental updates. An example:
```json
{
"command":"components-update",
"data":{
"enabled":false,
"name":"SMOOTHING"
}
}
```
### Session updates
The caller can subscribe to session updates (Hyperion instances found with
Bonjour/Zeroconf/Ahavi). These updates are meant to update the `sessions` section of
the caller's initial serverinfo. Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":[
"sessions-update"
],
"tan":1
}
```
These updates aren't incremental -- they contain all found entries on each update.
Example response with 2 HTTP server sessions (`_hyperiond-http._tcp`):
```json
{
"command":"sessions-update",
"data":[
{
"address":"192.168.58.169",
"domain":"local.",
"host":"ubuntu-2",
"name":"My Hyperion Config@ubuntu:8090",
"port":8090,
"type":"_hyperiond-http._tcp."
},
{
"address":"192.168.58.169",
"domain":"local.",
"host":"ubuntu-2",
"name":"My Hyperion Config@ubuntu:8099",
"port":8099,
"type":"_hyperiond-http._tcp."
}
]
}
```
### Priority updates
The caller can subscribe to priority updates. These updates are meant to update the
`priorities` and `priorities_autoselect` section of the caller's initial `serverinfo`.
Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":["priorities-update"],
"tan":1
}
```
Caller will get the complete data. Please note that if a color or effect is running with
a timeout > -1, the caller will receive new data each second. An example update:
```json
{
"command":"priorities-update",
"data":{
"priorities":[
{
"active":true,
"componentId":"GRABBER",
"origin":"System",
"owner":"X11",
"priority":250,
"visible":true
},
{
"active":true,
"componentId":"EFFECT",
"origin":"System",
"owner":"Warm mood blobs",
"priority":254,
"visible":false
},
{
"active":true,
"componentId":"COLOR",
"origin":"System",
"owner":"System",
"priority":40,
"value":{
"HSL":[65535,0,0],
"RGB":[0,0,0]
},
"visible":false
}
],
"priorities_autoselect":false
}
}
```
### LED Mapping updates
The caller can subscribe to LED mapping type updates. These updates are meant to update
the `imageToLedMappingType` section of the caller's initial `serverinfo`.
Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":["imageToLedMapping-update"],
"tan":1}
```
An example update:
```json
{
"command":"imageToLedMapping-update",
"data":{
"imageToLedMappingType":"multicolor_mean"
}
}
```
### Adjustment updates
The caller can subscribe to adjustment updates. These updates are meant to update the
`adjustment` section of the caller's initial `serverinfo`. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["adjustment-update"],
"tan":1
}
```
An example update:
```json
{
"command":"adjustment-update",
"data":[{
"backlightColored":true,
"backlightThreshold":0,
"black":[0,0,0],
"blue":[0,0,255],
"brightness":1,
"cyan":[0,127,127],
"gammaBlue":1.4,
"gammaGreen":1.4,
"gammaRed":1.4,
"green":[0,255,0],
"id":"default",
"magenta":[255,0,255],
"red":[255,0,0],
"white":[255,255,255],
"yellow":[255,255,0]
}]
}
```
### VideoMode updates
The caller can subscribe to videomode updates. These updates are meant to update the
`videomode` section of the cakker's initial `serverinfo`. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["videomode-update"],
"tan":1
}
```
An example update:
```json
{
"command":"videomode-update",
"data":{
"videomode": "2D"
}
}
```
### Effects updates
The caller can subscribe to effect list updates. These updates are meant to update the
`effects` section of the caller's initial `serverinfo`. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["effects-update"],
"tan":1
}
```
An example update:
```json
{
"command":"effects-update",
"data":{
"effects": [ ..All effects here..]
}
}
```
### Instance updates
The caller can subscribe to instance updates. These updates are meant to update the
`instance` section of the caller's initial serverinfo. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["instance-update"],
"tan":1
}
```
An example update. This is not incremental -- the caller will get the full set of
instances:
```json
{
"command":"instance-update",
"data":[
{
"instance": 0,
"running" : true,
"friendly_name" : "My First LED Hardware instance"
},
{
"instance": 1,
"running" : false,
"friendly_name" : "PhilipsHue LED Hardware instance"
}
]
}
```
### LEDs updates
The caller can subscribe to leds updates. These updates are meant to update the `leds`
section of the caller's initial `serverinfo`. Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":["leds-update"],
"tan":1
}
```
An example update. This is not incremental -- the caller willg et the full set of leds:
```json
{
"command":"leds-update",
"data": {
"leds" : [
{
"hmin":0.0,
"hmax":1.0,
"vmin":0.0,
"vmax":1.0
},
... more leds ...
]
}
}
```

View File

@ -1,43 +0,0 @@
# Configuration
Hyperion is fully configurable via web browser. The interface is fully responsive and created with touch devices in mind.
## Web Configuration
Open the web configuration by typing the IP address of your device and the port 8090 in your browser. The installation script will show you the address, if you don't know it. \
**Example:** `http://192.168.0.20:8090`
### Dashboard
<ImageWrap src="/images/en/user_config_dash.jpg" alt="Hyperion Web Configuration - Dashboard" />
#### Top right navbar
* **Arrows** - Switch between different LED hardware instances (If multiple are available)
* **TV** - Live led visualization
* **Wand/magic stick** - Wizards that guide you through color calibration and more
* **Wrench** - Settings for language selection, settings level, logout, ...
**Left sidebar**
* **Dashboard** - Yes, here we are.
* **Configuration** - All available settings
* **Remote Control** - Control Hyperion like any other Hyperion remote application
* **Effects Configurator** - Create new effects based on effect templates
* **Support** - Where you get support and how to support us (and why)
* **System** - Inspect your log messages, upload a report for support, credits page, etc
#### Page
* The **Information** panel shows some important/useful informations. With a small smart access area with important actions.
* The **Component status** shows always the latest state (enabled/disabled) of the components
::: tip Hashtag navigation
The web configuration supports hashtags for sitenames, so you could directly open a specific page by calling the hashtag. **Example:**`http://192.168.0.20:8090/#remote` - will open the remote control page.
:::
### Configuration
We added additional information(s) to each option. Some topics require additional attention which are covered here. If you need more help or something lacks of infos, just dive into our Forum.
#### Language
By default, the web configuration selects the language based on your browser locale or best matching next to. So no configuration is required. In case you want to start learning Hyperion in another language, select from the provided once. \
Want to contribute a new translation? It's easy! Checkout: [Contribute to Hyperion](https://github.com/hyperion-project/hyperion.ng#contributing).
<ImageWrap src="/images/en/user_config_lang.jpg" alt="Hyperion Web Configuration - Language" />
#### Settings level
Settings level prevents a option flooding for new users. While the **Default** level is for beginners and has the lowest amount of options the **Advanced** is for people that want to or need to dive a little deeper. **Expert** is for experts, you shouldn't need it that often.
<ImageWrap src="/images/en/user_config_access.jpg" alt="Hyperion Web Configuration - Settings level" />

View File

@ -1,55 +0,0 @@
# HyperBian
Is a ready to use image for your Raspberry Pi. Based on the original Raspberry Pi Foundation image "Raspbian lite". Hyperion is already pre installed. So simply
1. Download
2. Burn image on SD
3. Power on your Pi
4. Visit with your Browser `http://IpOfYourPi:8090` for configuration
## Requirements
* SD card with at least 2GB size
* Raspberry Pi
* Linux/Mac/Windows + SD card read/writer
## Installation
* Download the image here: [HyperBian Download](https://github.com/Hyperion-Project/HyperBian/releases)
* Extract HyperBian-XXXX.img out of the HyperBian.zip
* Burn the extracted HyperBian-XXXX.img to your SD card. Below 3 instructions for the specific system
* On Windows: [INSTALLING OPERATING SYSTEM IMAGES USING WINDOWS](https://www.raspberrypi.org/documentation/installation/installing-images/windows.md)
* On Mac: [INSTALLING OPERATING SYSTEM IMAGES ON MAC OS](https://www.raspberrypi.org/documentation/installation/installing-images/mac.md)
* On Linux: [INSTALLING OPERATING SYSTEM IMAGES ON LINUX](https://www.raspberrypi.org/documentation/installation/installing-images/linux.md)
* In case your Raspberry Pi has WLAN or you want to use a WLAN stick, you could pre-configure the WLAN SSID and password before you plugin the SD in your Pi. See [HyperBian WLAN](#hyperbian-wlan)
* Optional: Enable SSH [HyperBian SSH](#HyperBian-SSH)
::: tip
As a image is already outdated the moment you create it. We update it once a week with latest sources from the Raspberry Pi Foundation. Or upon a new Hyperion release.
:::
### HyperBian WLAN
In case you want to use WLAN with your Raspberry Pi, you can include the WLAN SSID and password after you burned the HyperBian-XXXX.img to your SD card for auto configuration on first boot.
Open the SD card with a file explorer. It's called "boot".
- Create a new text file
<ImageWrap src="/images/en/user_hyperbian_wpa_suppli1.jpg" alt="Create a new textfile" />
- Rename it to "wpa_supplicant.conf"
<ImageWrap src="/images/en/user_hyperbian_wpa_suppli2.jpg" alt="Rename to wpa_supplicant.conf"/>
- Add your WLAN credentials, replace **YOUR_SSID** and **YOUR_PASSWORD** with your values
```
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB
network={
ssid="YOUR_SSID"
psk="YOUR_PASSWORD"
key_mgmt=WPA-PSK
}
```
<ImageWrap src="/images/en/user_hyperbian_wpa_suppli3.jpg" alt="Add your WLAN config"/>
- Save it! You are done, the WLAN will be configured during next boot
### HyperBian SSH
You should never need it for daily usage, but for completion: To enable SSH access, plugin your sd card with HyperBian already installed into your computer, and open the "boot" partition with a file explorer. Create a empty file named `ssh` in the root directory (without file extension). SSH will be enabled now on next boot. \
**SSH LOGIN**
- User: pi
- Password: raspberry
<ImageWrap src="/images/en/user_hyperbian_ssh.jpg" alt="Enable SSH"/>

View File

@ -1,58 +0,0 @@
# Install Hyperion
Hyperion supports various platforms for installation, as package or portable .zip.
## Requirements
### Supported Systems
* Raspberry Pi (See also [HyperBian](/en/user/HyperBian))
* Debian 9 | Ubuntu 16.04 or higher
* Mac OS
* Windows 10
**Please note that some arm devices have limited support in terms of screen capturing**
### Supported Browsers
Hyperion will be configured and controlled trough a web interface.
* Chrome 47+
* Firefox 43+
* Opera 34+
* Safari 9.1+
* Microsoft Edge 14+
::: warning Internet Explorer
Internet Explorer is not supported
:::
## Install Hyperion
* Raspberry Pi you can use [HyperBian](/en/user/HyperBian.md) for a fresh start. Or use the install system
* We provide installation packages (.deb) to install Hyperion with a single click on Debian/Ubuntu based systems.
* Mac OSX - currently just a zip file with the binary
* Windows 10 you can use the .exe file from [Release page](https://github.com/hyperion-project/hyperion.ng/releases) for a single click installation.
### Debian/Ubuntu
For Debian/Ubuntu we provide a .deb file. A one click installation package that does the job for you. \
Download the file from the [Release page](https://github.com/hyperion-project/hyperion.ng/releases) \
Install from commandline by typing. \
`sudo apt install ./Hyperion-2.0.0-Linux-x86_64.deb` \
Hyperion can be now started from your start menu.
### Fedora
For Fedora we provide a .rpm file. A one click installation package that does the job for you. \
Download the file from the [Release page](https://github.com/hyperion-project/hyperion.ng/releases) \
Install from commandline by typing. \
`sudo dnf install ./Hyperion-2.0.0-Linux-x86_64.rpm` \
Hyperion can be now started from your start menu.
### Windows 10
For Windows 10 we provide a .exe file. A one click installation package that does the job for you. \
Download the file from the [Release page](https://github.com/hyperion-project/hyperion.ng/releases) \
Install by executing the file. \
After following the instructions Hyperion can be now started from your start menu.
## Uninstall Hyperion
On Debian/Ubuntu you can remove Hyperion with this command \
`sudo apt remove hyperion`\
On Windows 10 Hyperion can be removed using the Windows 10 "Programs and Features" settings.
### Hyperion user data
Hyperion stores user data inside your home directory (folder `.hyperion`).

View File

@ -1,167 +0,0 @@
---
sidebarDepth: 2
---
# LED Hardware
Hyperion supports a lot of different controllers and led chips. Also network communication is possible, therefore we also support Philips Hue, AtmoOrb and more.
## General Settings
Applicable for all led hardware implementations \
* RGB byte order: If you want to check this value, use the wizard.
* Refresh time: If no source is active and the led hardware component is enabled, this will update by the given interval time the led hardware with black color.
## Specific Settings
Each LED hardware has specific settings which are explained here
### SPI
Are 4 wire leds which can be powered via SPI of a Raspberry Pi or an Arduino (which is USB connected to your computer/HTPC/Pi)
#### apa102
APA 102. These LEDs are known for a good color spectrum (converting a data signal to the wanted color).
#### ws2801
The color spectrum of these leds is bad.
#### lpd6803
#### lpd8806
#### p9813
#### sk6812spi
The SK6812 are **3** wire leds, you could also drive them via spi.
#### sk6822spi
The SK6822 are **3** wire leds, you could also drive them via spi.
#### sk9822
The SK9822 are **4** wire leds compatible to APA 102 with addition of global brightness control.
#### ws2812spi
The WS2812 are **3** wire leds, you could also drive them via spi.
### USB
Plug and play. The following controllers are supported.
#### adalight
Most used because it's cheap and easy! An Arduino powered by an adalight sketch. We provide a modified version of it. Checkout TUTORIAL
#### atmo
#### dmx
#### file
#### hyperionusbasp
#### lightpack
#### multilightpack
#### paintpack
#### rawhid
#### sedu
#### tpm2
### Network
Hue bridges, nodeMCU, AtmoOrbs, [WLED](https://github.com/Aircoookie/WLED) everything that is reachable over network.
#### philipshue
The well known [Philips Hue Bridge + Bulbs](https://www.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=philips+hue+starter+set&rh=i%3Aaps%2Ck%3Aphilips+hue+starter+set&tag=hyperionpro05-20) is supported. How to configure them with Hyperion? Checkout: Web configuration
#### Entertainment API
::: danger Photosensitive seizure warning
Certain individuals may experience discomfort when exposed to quick flashes/patterns of light.
Please refrain from using entertainment mode immediately if you feel any discomfort or have any known health conditions. Please consult a physician under those circumstances. Make sure your entertainment room is well-lit.
Hyperion cannot be held liable for any foreseeable, or unforeseeable, negative or harmful impact.
:::
##### Requirements
* Before you start, the Entertainment API requires at least one entertainment group/area with minimum one assigned lamp! Checkout: [Entertainment groups / areas](#entertainment-groups--areas)
* A normal Hue group, does NOT work with the Hue Entertainment API!
* Check the "Use Hue Entertainment API" option and use the Philips Hue Entertainment wizard at the web configuration for configuration (available at led hardware section)!
* The Entertainment API requires also a username and a suitable clientkey. Checkout: [Philips Hue Entertainment wizard](#philips-hue-entertainment-wizard)
##### Philips Hue Entertainment wizard
* In the wizard, your Hue Bridge is automatically discovered via the Philips Hue Cloud when it is registered. If not, try entering the bridge IP address and click the "retry" icon / button next to the IP entry field.
* If only the username is known or you start from scratch, create a new user with the Philips Hue Entertainment wizard and a clientkey will automatically generated.
* If no Entertainment group / area was found on the bridge you are using, the wizard switches back to the classic version and deactivates the use of the Hue Entertainment API!
* Username, clientkey and Entertainment group / area ready? Select your Entertainment group / area, you would like to use and fine-tune your preselected screen positions for each lamp.
* Don't forget to save your changes! ;)
##### Bridge requirements / limits
* To use the Philips Hue Entertainment API, the bridge must use at least API version 1.22!
* Only one Entertainment group / area can be active at one time on a single Hue Bridge!
##### Multiple and / or none original Hue bridges
* Automatic detection will only find the first available bridge.
* If your bridge wasn't found or was found, but not the one you want to use, manually enter the desired bridge IP address and click the "retry" icon / button next to the IP entry field.
##### Entertainment groups / areas
* Entertainment groups / areas can be created using the original Philips Hue app.
* Set also the right z-axis (Ground height, TV height and Ceiling height) for each lamp within the configuration of the Entertainment group / area. Tapping each lamp changes the height and will be recognized it in the Philips Hue Entertainment wizard to also preselect the correct screen position.
* You can connect up to 10 Philips Hue or Friends of Hue color-capable lights per Entertainment group / area.
* When a Entertainment group / area is used with the Entertainment API, you can't control any of the lamps in the Entertainment group / area, until the Entertainment API stops!
#### Advanced Settings
##### Signal detection
* The Entertainment API is a permanent stream that continuously sends color information to the bridge. That's why the signal detection came into play.
* With the `Signal detection timeout on black` option, you can control how long all lamps are set to black, before the Entertainment API stops and the previous lamp state will be recovered.
* Set the ms value higher, so longer dark scenes in movies will not stop the Entertainment API.
* The Entertainment API automatically restarts when color information other than black is available to send.
* Some grabbers do not provide real black, but rather dark gray, so black = 0 never occurs. With the option `Signal detection brightness minimum` you can set the minimum brightness which is considered black. The range can be set from 0 = 0% to 1 = 100%, e.g. 0,005 = 0.5%. If 0 doesn't' work for your setup, increase this value in 0,005 steps. It's like the thresholds for USB Capture.
##### Brightness *Settings may be removed in future releases*
* Set / leave `brightness factor` back to 1 (default) - classic low brightness bug is fixed
* Set / leave `brightness minimum` to 0 (default) - you can set a minimum brightness, so the lamps will never be off
* Set / leave `brightness maximum` to 1 (default) - you can set a maximum brightness, if you don't want the whole room to light up in bright scenes
* Value range for brightness minimum / maximum are: 0 = 0% to 1 = 100%, E.g. 0,05 = 5% / 0,5 = 50%
* The brightness factor is a multiplier for the input brightness, means E.g. 50% input brightness * brightness factor (e.g. 1,5) = new 75% brightness.
* __Be warned__:
If you change the brightness factor / minimum / maximum to a value other than the default value, the color rendering will also change!!!
E.g. Dark / Black will appear as a deep dark blue, if you raise the minimum brightness, because the deepest color inside the hue light system is a deep blue, because black is not a color, it's only off.
__AND__ you can miss the entire Entertainment API experience ;)
::: warning Fast uncontrolled colors / flickering
* The color information for each lamp, depends on the input signal from your grabber source, the defined screen position to use for the lamp (like any other led configuration) and the used capture framerate!
* Input signals with noise and other image disturbances can cause this effect of rapidly changing colors / flickering. For more information on how to reduce this problem, see the next tip:
:::
::: tip Activate smoothing in image processing!
This allows the extremely fast color / flicker to be controlled very well.
These values work well, but decide for yourself:
Time: 80 - 120 ms
Update frequency: 35 - 40 Hz - higher values leads to faster color change / flickering again
Update delay: 0 ms
Continuous output: no - does not have to, since the last color values are stored in the respective lamp
:::
##### Configuration Tips & Tricks
* Color calibration is not required, you can keep the default values.
* To enable/disable the active Entertainment group / area from Hyperion, disable Hyperion or just the led hardware component. The previous lamp state will be recovered - other solutions may come in future releases - Hint: [Signal detection](#signal-detection)
#### Classic Philips Hue usage without the Entertainment API
##### Configuration Tips & Tricks
* Use the Philips Hue wizard at the web configuration for configuration (available at led hardware section)!
* Color calibration is not required, you can keep the default values.
* If the brightness is to low for you and Hyperion is already at 100% you can higher the brightness factor at the web configuration -> LED hardware
* Brightness compensation influences the brightness across different color (Adjust at the color section)
* To enable/disable the bridge control from Hyperion, disable Hyperion or just the led hardware component. The previous lamp state will be recovered
#### WLED
WLED is connected to Hyperion by selecting the "Controller type" als WLED and entering the IP-Adress of your WLED instance in the Hyperion UI.\
Hyperion uses the brightness setting set in WLED. E.g. if you set the brightness in WLED to 10% the LEDs will light up to a maximum of 10%. If you would like Hyperion to override the brightness setting of WLED and use the maximum brightness you can do so by going to the WLED configuration -> Sync. Settings and enabling "Force max brightness".
#### atmoorb
#### tpm2net
#### udpe131
#### udph801
#### udpraw
#### tinkerforge
#### fadecandy
### Raspberry Pi
Just for the Raspberry Pi!
#### ws281x
Driving all kinds of WS281X stripes. Due to mixed feedback we recommend adalight or Raspberry Pi SPI.
#### piblaster
[PiBlaster on Github](https://github.com/sarfata/pi-blaster)

View File

@ -1,2 +0,0 @@
# User Documentation
All you need to know about Hyperion

View File

@ -1,194 +0,0 @@
# Advanced
Specific topics with details
[[TOC]]
## LED Layout
Hyperion assigns each single led a specific position at the picture. These positions are squares and to create a square you need 4 values (top edge, bottom edge, left edge, right edge). These edges are reflected in `hmin`, `hmax` for horizontal and `vmin`, `vmax` for vertical. They have a value range from `0.0` to `1.0`.
<ImageWrap src="/images/en/user_ledlayout.jpg" alt="Hyperion Led Layout">
Assignment of LED edges
</ImageWrap>
So let's have a closer look. Following a single led definition:
``` json
{
"hmax": 0.2,
"hmin": 0,
"vmax": 0.2,
"vmin": 0
}
```
Let's visualize the example above!
<ImageWrap src="/images/en/user_ledlayout1.jpg" alt="Hyperion Led Layout">
A single led definition
</ImageWrap>
So let us add 2 more leds to make it more clear \
**The order is important! The first entry is the first led, the second the second led, ...**
``` json
{
"hmax": 0.2,
"hmin": 0,
"vmax": 0.2,
"vmin": 0
},
{
"hmax": 0.5,
"hmin": 0.3,
"vmax": 0.5,
"vmin": 0.3
},
{
"hmax": 1.0,
"hmin": 0.7,
"vmax": 1,
"vmin": 0.7
}
```
<ImageWrap src="/images/en/user_ledlayout2.jpg" alt="Hyperion Led Layout">
Now with three LEDs
</ImageWrap>
### Additional properties
You may connected different led stripe charges with different RGB byte orders. You can overwrite the global RGB byte order by adding a `colorOrder` property to all leds that require a different one.
``` json
{
"hmax": 0.2,
"hmin": 0,
"vmax": 0.2,
"vmin": 0,
"colorOrder":"gbr"
},
{
"hmax": 0.5,
"hmin": 0.3,
"vmax": 0.5,
"vmin": 0.3
},
{
"hmax": 1.0,
"hmin": 0.7,
"vmax": 1,
"vmin": 0.7
}
```
In this example the first led will be `gbr`, the other leds will be assigned to the global RGB order that has been defined at the led hardware section.
### Edit with Web Configuration
While editing these values in a local texteditor is a little bit weird, you could edit them at the web configuration!
- Make sure you raised the [Hyperion Settings level](../Configuration.md#settings-level) to **Advanced**.
- Navigate to Configuration -> LED Hardware and switch to the LED Layout tab. You will notice a new section **Generated/Current LED Configuration**.
<ImageWrap src="/images/en/user_ledlayout3.jpg" alt="Hyperion Led Layout" />
You could freely edit the values, show a preview on the right side by clicking **Update Preview**. When you are happy with the changes don't forget to save.
## Blackbar detection
Explain the differences between the available modes for blackbar detection.
* **Default:** 3 scanlines in each direction (X Y) - fastest detection
* **Classic:** The original implementation - lower cpu time (legacy for RPi 1) just scan the top one third of the picture which leads to a slow detection and trouble with TV channel logo.
* **OSD:** Based on the default mode - not that effective but prevents border switching which may caused of OSD overlays (program infos and volume bar).
* **Letterbox:** Based on the default mode - only considers blackbars at the top and bottom of the picture, ignoring the sides.
<ImageWrap src="/images/en/user_bbmodes.jpg" alt="Hyperion Blackbar detection modes" />
## Gamma Curve
Gamma values in a graphic. AS you see 1.0 is neutral. Lower than 1.0 increase the color, higher reduce color.
<ImageWrap src="/images/en/user_gammacurve.png" alt="Hyperion Gamma Curve" />
## CLI
All executables shipped with Hyperion have some command line arguments/options
### hyperiond
The heart of Hyperion
``` sh
# Show the version/build date/commit of Hyperion
hyperiond --version
# Reset current adminstration password back to 'hyperion'
hyperiond --resetPassword
# Overwrite the path for user data (which defaults to your home directory)
hyperiond --userdata /temp/anotherDir
# Overwrite log level temporarily: hyperiond -s for silent -v for verbose and -d for debug
hyperiond -d
# Export effects to directory
hyperiond --export-effects /tmp
# Run Hyperion in desktop mode
hyperiond --desktop
```
::: tip
If a path name contains spaces, surround it with `“`.
`hyperiond --userdata "/temp/another Dir"`
:::
### hyperion-remote
hyperion-remote is a command line tool which translates given arguments to JSON commands and sends them to the Hyperion JSON-RPC. Easy to use for scripts. It supports nearly all commands that Hyperion provides.
``` sh
# Get a list of all available commands
hyperion-remote -h
# Set a color by using HTML color names
hyperion-remote -c aqua
# Set color with hex value
hyperion-remote -c FF7F50
# Set color with a duration of 5 seconds instead endless
hyperion-remote -c FF7F50 -d 5000
# Start an effect
hyperion-remote -e "Rainbow swirl"
# with a duration of 8 seconds instead endless
hyperion-remote -e "Rainbow swirl" -d 8000
# Target a specific instance
# ATTENTION: Hyperion instances will synchronize with the Instance Syncing feature by default
# You can configure the behaviour for each instance
hyperion-remote -I "My cool instance name"
# Or
hyperion-remote --instance "My cool instance name"
# Example set effect for instance
hyperion-remote --instance "My cool instance name" -e "Rainbow swirl"
```
::: tip
Hyperion remote will search for a Hyperion server automatically. So you can even use that on another device in your local network without providing a ip/port
:::
### hyperion-capture
We deliver also stand alone capture apps right in your Hyperion directory. They are called hyperion-dispmanx, hyperion-osx, hyperion-x11, hyperion-amlogic, hyperion-framebuffer, hyperion-qt. Depending on your platform you have more or less.
All these application can be started independent from Hyperion and all of these have slightly different options. They communicate with the flatbuffer interface of Hyperion. So let's start one of them! In this example i use dispmanx for Raspberry Pi, so let us check the available options.
``` sh
hyprion-dispmanx -h
-f, --framerate <framerate> Capture frame rate [default: 10]
--width <width> Width of the captured image [default: 64]
--height <height> Height of the captured image [default: 64]
--screenshot Take a single screenshot, save it to file and quit
-a, --address <address> Set the address of the hyperion server [default: 127.0.0.1:19445]
-p, --priority <priority> Use the provided priority channel (suggested 100-199) [default: 150]
--skip-reply Do not receive and check reply messages from Hyperion
-h, --help Show this help message and exit
--crop-left <crop-left> pixels to remove on left after grabbing
--crop-right <crop-right> pixels to remove on right after grabbing
--crop-top <crop-top> pixels to remove on top after grabbing
--crop-bottom <crop-bottom> pixels to remove on bottom after grabbing
--3DSBS Interpret the incoming video stream as 3D side-by-side
--3DTAB Interpret the incoming video stream as 3D top-and-bottom
# Let's start with capture interval of 15, width of 100 and a height of 100
hyperion-dispmanx -a 192.168.0.20:19445 -f 15 --width 100 --height 100
```

View File

@ -1,76 +0,0 @@
# Support Request
In case you need support or you found a bug it's all about informations that you need to deliver.
## Usual request
For this purpose and to save a lot of time we included a report creation and upload function into the web configuration.
So visit your web configuration and click on System -> Log. Now you click on the button "Upload report for support request".
> Image of report tool
If everything has gone well, you will notice a Link below the button. Add this link to your support request at our [Hyperion Project Forum](https://forum.hyperion-project.org).
## Segmentation faults
Debugging segmentation faults requires a bunch of work, if we don't own your hardware (idr one of these plenty ARM systems) or can't reconstruct the segmentation fault we need a backtrace log from you. In order to create one, follow these steps.
- You need a "Debug" version of Hyperion, download and install it over your existing installation.
- Install "GDB", gbd is a tool which is often used for debugging. Get it from the software repository of your distribution (Debian e.g. `sudo apt-get install gdb`
### Steps of execution
* Open a terminal
* Make sure Hyperion is NOT running, this can be done by typing `sudo service hyperiond stop` into the terminal and press enter
* Type in `gdb` and press enter. You will now see the gdb welcome information and a "(gdb)" in front of your cursor
* Tell gdb where "hyperiond" is located, usually at /usr/share/hyperion/bin/hyperiond. Prepend "file" to the path. So type into terminal something like that and press enter: `file /usr/share/hyperion/bin/hyperiond`
* gdb should tell you now that the binary has been loaded with it's symbols etc
* Now type in `run` and press enter, this will start Hyperion. Now you can use Hyperion as usual, repeat the steps you did to create a segmentation fault.
* A segmentation fault happened, when Hyperion stops responding and you see something like this as last message at the terminal: `Thread 1 "hyperiond" received signal SIGSEGV, Segmentation fault.`
* Now type in `backtrace` and press enter, add the backtrace to your support request thread at our forum. [Hyperion Project Forum](https://forum.hyperion-project.org)
* To quit gdb press enter and type in `quit`, you can start Hyperion again with `sudo service hyperiond start`. It's not recommended to use "Debug" Hyperion builds in production, just install the "Release" version again.
### Example backtrace log
```
(gdb) backtrace
#0 0x0000000000000000 in ?? ()
#1 0x00000000006173f2 in LinearColorSmoothing::queueColors (this=0xfdfa70,
ledColors=std::vector of length 34, capacity 34 = {...})
at /home/hyperion/Dokumente/hyperion.ngBeta/libsrc/hyperion/LinearColorSmoothing.cpp:153
#2 0x0000000000617374 in LinearColorSmoothing::updateLeds (this=0xfdfa70)
at /home/hyperion/Dokumente/hyperion.ngBeta/libsrc/hyperion/LinearColorSmoothing.cpp:143
#3 0x0000000000609652 in LinearColorSmoothing::qt_static_metacall (
_o=0xfdfa70, _c=QMetaObject::InvokeMetaMethod, _id=1, _a=0x7fffffffd190)
at /home/hyperion/Dokumente/hyperion.ngBeta/build/libsrc/hyperion/moc_LinearColorSmoothing.cpp:85
#4 0x00007ffff59abd2a in QMetaObject::activate(QObject*, int, int, void**) ()
from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#5 0x00007ffff59b85c8 in QTimer::timerEvent(QTimerEvent*) ()
from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#6 0x00007ffff59acbb3 in QObject::event(QEvent*) ()
from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#7 0x00007ffff78a505c in QApplicationPrivate::notify_helper(QObject*, QEvent*)
() from /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
#8 0x00007ffff78aa516 in QApplication::notify(QObject*, QEvent*) ()
from /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
#9 0x00007ffff597d38b in QCoreApplication::notifyInternal(QObject*, QEvent*)
---Type <return> to continue, or q <return> to quit---
() from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#10 0x00007ffff59d25ed in QTimerInfoList::activateTimers() ()
from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#11 0x00007ffff59d2af1 in ?? () from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#12 0x00007ffff4572127 in g_main_context_dispatch ()
from /lib/x86_64-linux-gnu/libglib-2.0.so.0
#13 0x00007ffff4572380 in ?? () from /lib/x86_64-linux-gnu/libglib-2.0.so.0
#14 0x00007ffff457242c in g_main_context_iteration ()
from /lib/x86_64-linux-gnu/libglib-2.0.so.0
#15 0x00007ffff59d37cf in QEventDispatcherGlib::processEvents(QFlags<QEventLoop::ProcessEventsFlag>) () from /usr/lib/x86_64-linux-
gnu/libQt5Core.so.5
#16 0x00007ffff597ab4a in QEventLoop::exec(QFlags<QEventLoop::ProcessEventsFlag>) () from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#17 0x00007ffff5982bec in QCoreApplication::exec() ()
from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
#18 0x00000000005d9279 in main (argc=1, argv=0x7fffffffde08)
at /home/hyperion/Dokumente/hyperion.ngBeta/src/hyperiond/main.cpp:337
```
## Report Privacy Policy
Hyperion gathers the following informations and uploads them to our server.
* System informations (OS, Version, Kernel, Arch) Hyperion runs on.
* Current state (active components, active priorities, webconfig settings)
* Browser and OS
* Configuration file content
* Log (if available)
No additional data is acquired. We use this informations just for support requests.

View File

@ -1,32 +0,0 @@
{
"name": "hyperion-docs",
"version": "1.0.0",
"description": "Hyperion Documentation",
"homepage": "https://www.hyperion-project.org",
"author": "brindosch",
"private": true,
"licence": "MIT",
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs",
"docs:serve": "vuepress serve docs --build --open"
},
"dependencies": {
"vuepress": "^1.4.1",
"vuepress-plugin-medium-zoom": "^1.1.8",
"vuepress-plugin-redirect": "^1.2.3"
},
"devDependencies": {
"@vuepress/plugin-back-to-top": "^1.4.1",
"@vuepress/plugin-pwa": "^1.4.1",
"babel-eslint": "^10.1.0",
"eslint": "^6.8.0",
"eslint-plugin-vue": "^6.2.2",
"vuepress-plugin-serve": "^2.0.2"
},
"engines": {
"node": ">= 10.16.0",
"npm": ">= 5.6.0",
"yarn": ">= 1.19.0"
}
}

File diff suppressed because it is too large Load Diff