### Quick start
#### Initialization & Configuration
Before you can start your Khome application, you need to initialize and configure it. Here you have two choices to do so:
1. The functional way
```kotlin
khomeApplication { //this: Khome
configure { //this: Configuration
host = "localhost"
port = 8123
accessToken = "Your super secret token"
secure = false
}
}
```
2. Set environment variables
Alternatively, you can use env variables to configure home.
```.env
HOST=192.169.178.101
```
##### Required Parameters
- **host**: String
Local ip address or url from your Home-Assistant server instance
- **port**: Int
The port of Home-Assistant (defaults to 8123)
- **accessToken**: String
You need to create a [long-lived access token](https://developers.home-assistant.io/docs/en/auth_api.html#long-lived-access-token).
You can do so within the Lovelace UI. Just go to your user profile, scroll to the bottom, and generate one.
- **secure**: Boolean
If you want to establish a secure WebSocket connection, you need to set this parameter to true (defaults to false).
#### Connect to the web socket API
```kotlin
val KHOME = khomeApplication()
fun main() {
//...
KHOME.runBlocking()
}
```
By calling the `KhomeApplication::runBlocking` method, you establish a connection to the Home-Assistant WebSocket API and run the start sequences like authentication, entity registration validation, and so on.
When all went as supposed, you should see the following output in your console.
```bash
[main] INFO Authenticator - Authentication required!
[main] INFO Authenticator - Sending authentication message.
[main] INFO Authenticator - Authenticated successfully to homeassistant version 0.111.0
[main] INFO ServiceStoreInitializer - Requested registered homeassistant services
[main] INFO ServiceStoreInitializer - Stored homeassistant services in local service store
[main] INFO EntityStateInitializer - Requested initial entity states
[main] INFO EntityRegistrationValidation - Entity registration validation succeeded
[main] INFO StateChangeEventSubscriber - Successfully started listening to state changes
```
## Start writing your home automation application
Basically, a Khome application is a collection of observers attached to some entities. For your convenience, Khome comes with a lot of predefined entity types.
For most uses cases, [here is all you need](PredefinedEntityTypes.md) to build your application. Since home assistant evolves rapidly and has the ability to be extended with custom integrations,
it comes along with a low-level API to build your own entities, based on your needs. You find more on that topic in the [Build your own entities](BuildEntitiesFromScratch.md) section.
The following examples to get you off and running are based on the [predefined entity types](PredefinedEntityTypes.md) and the [notification API](NotificationApi.md) provided by Khome.
For a deeper understanding of Khome's capabilities, we encourage you to read the [Sensors, Actuators, and Observer](SensorsAndActuators.md) section.
### Lower complexity
1. Turn on a light, when a motion sensor detects movement, and the sun is below horizon.
```kotlin
val KHOME = khomeApplication()
val HallwayLight = KHOME.DimmableLight("hallway_main".objectId)
val HallwayMotionSensor = KHOME.MotionSensor("hallway".objectId)
val Sun = KHOME.Sun()
fun main() {
HallwayMotionSensor.attacheObserver {
if (Sun.measurement.value == SunValue.BELOW_HORIZON) {
when(measurement.value) {
ON -> HallwayLight.turnOn()
OFF -> HallwayLight.turnOff()
}
}
}
KHOME.runBlocking()
}
```
2. Iterate over a list of covers and set them to a specific position when the sun has risen.
```kotlin
val KHOME = khomeApplication()
val Sun = KHOME.Sun()
val BedRoomCovers = listOf(
KHOME.PositionableCover("bedroom_one".objectId),
KHOME.PositionableCover("bedroom_two".objectId),
KHOME.PositionableCover("bedroom_three".objectId),
KHOME.PositionableCover("bedroom_four".objectId),
)
fun main() {
Sun.onSunrise {
for (cover in BedRoomCovers) {
cover.desiredState = CoverState(value = CoverValue.OPEN, position = 60)
}
}
}
```
### Intermediate complexity
1. Send a notification to your mobile app when door sensor reports "door open" at night.
```kotlin
val KHOME = khomeApplication()
val GardenShedDoor = KHOME.ContactSensor("garden_shed".objectId)
val LateNight = KHOME.DayTime("late_night".objectId)
enum class MobilePhone {
MY_PHONE
}
fun main() {
GardenShedDoor.attachObserver {
if (LateNight.measurement.value == SwitchableValue.ON &&
history[1].state.value == ContactValue.CLOSED &&
measurement.value == ContactValue.OPEN
) {
KHOME.notifyMobileApp(MobilePhone.MY_PHONE) {
title = "INTRUDER ALARM"
message = "Garden shed door opened"
data {
sound(critical = 1, volume = 1.0)
}
}
}
}
}
```
### Higher complexity
1. When the Television got turned on, the livin groom covers get set to a specific position to comfortably watch some tv.
The previous positions get stored in a state store and when the tv got turned off, the covers get reset to the former positions.
```kotlin
val KHOME = khomeApplication()
val TelevisionLivingroom = KHOME.Television("tv_livingroom".objectId)
val ResetStateHistory = mutableMapOf()
val televisionWatchingCoverPosition =
KHOME.InputNumber("television_watching_cover_position".objectId).actualState.toInt()
val defaultCoverPosition = 75
val LivingRoomCovers = listOf(
KHOME.PositionableCover("livingroom_one".objectId),
KHOME.PositionableCover("livingroom_two".objectId),
KHOME.PositionableCover("livingroom_three".objectId)
)
fun main() {
TelevisionLivingroom.attachObserver {
if (turnedOn) {
for (cover in LivingRoomCovers) {
ResetStateHistory[cover] = cover.actualState
cover.setCoverPosition(televisionWatchingCoverPosition)
}
}
if (turnedOff) {
for (cover in LivingRoomCovers) {
cover.desiredState = ResetStateHistory[cover] ?: CoverState(CoverValue.OPEN, defaultCoverPosition)
}
}
}
}
```