Metadata-Version: 2.4
Name: nikki-streams
Version: 1.0.0
Summary: Turn your Android phone into a programmable IoT device. nikki Streams is an asynchronous Python SDK for communicating with the nikki Streams mobile application over WebSocket.
Author-email: nikki Build <dev.nikki.build@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/nikki-build/streams.python
Project-URL: Repository, https://github.com/nikki-build/streams.python.git
Project-URL: Issues, https://github.com/nikki-build/streams.python/issues
Keywords: nikki,nikki-build,nikki-streams,python,asyncio,websocket,iot,android,mobile,device,sensor,accelerometer,gyroscope,orientation,gravity,pose,ambient-light,proximity,magnetometer,barometer,gps,gnss,microphone,nfc,notification,haptic,vibration,automation,realtime
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets<16.0,>=15.0
Dynamic: license-file

# nikki streams Python SDK

Turn your Android phone into a programmable IoT device.

**nikki streams** is an asynchronous Python SDK for communicating with the nikki streams mobile application over WebSocket. It provides real-time access to device sensors and allows you to control notifications, haptic feedback, lighting, volume, and more.

---

# Features

- Fully asynchronous (`asyncio`)
- Simple API
- Automatic WebSocket URL generation
- Local network validation
- Session-based authentication
- Multiple device support
- Real-time event callbacks
- Type hints
- Lightweight dependency (`websockets`)

---

# Installation

```bash
pip install nikki-streams
```

or install locally

```bash
pip install -e .
```

---

# Initialize SDK

```python
from nikki_streams import SDK

SDK.initialize("PnE337815216")
```

The session ID only needs to be initialized once.

---

# Create a Device

```python
from nikki_streams import SDK

SDK.initialize("PnE337815216")


def callback(event):
    print(event)


device = SDK.create_device(
    "192.168.1.69:3000",
    callback
)
```

The SDK automatically converts

```
192.168.1.69:3000
```

into

```
ws://192.168.1.69:3000?sessionID=PnE337815216
```

---

# Connect

```python
await device.connect()
```

Disconnect

```python
await device.disconnect()
```

---

# Light

```python
await device.set_light_status(True)

await device.set_light_status(False)
```

Payload

```json
{
  "light": true
}
```

---

# Volume

```python
await device.set_volume(80)
```

Range

```
0 - 100
```

Payload

```json
{
  "volume": 80
}
```

---

# Haptic Feedback

```python
await device.set_haptic()
```

Custom duration

```python
await device.set_haptic(500)
```

Payload

```json
{
  "haptic": true,
  "duration": 1000
}
```

---

# Notification

```python
await device.set_notification(
    "Hello",
    "Welcome to nikki streams"
)
```

Payload

```json
{
  "notification": {
    "title": "Hello",
    "sub": "Welcome to nikki streams"
  }
}
```

---

# Events

All events are delivered through the callback supplied to `create_device()`.

## Connected

```python
CallbackPayload(
    type="statusChange",
    data="connected"
)
```

---

## Disconnected

```python
CallbackPayload(
    type="statusChange",
    data="disconnected",
    error=None
)
```

---

## Incoming Sensor Data

```python
CallbackPayload(
    type="data",
    data={
        "sensor": "accelerometer",
        "x": 0.12,
        "y": 4.91,
        "z": 9.81
    }
)
```

---

# Complete Example

```python
import asyncio

from nikki_streams import SDK


SDK.initialize("PnE337815216")


def callback(event):
    print(event)


async def main():

    device = SDK.create_device(
        "192.168.1.69:3000",
        callback
    )

    await device.connect()

    await device.set_light_status(True)

    await device.set_volume(60)

    await device.set_haptic()

    await device.set_notification(
        "Python SDK",
        "Connected successfully"
    )

    await asyncio.sleep(5)

    await device.disconnect()


asyncio.run(main())
```

---

# Supported Device Features

- Notifications
- Haptic Feedback
- Light Control
- Volume Control

---

# Supported Sensors

The nikki streams mobile application can stream real-time data from supported sensors, including:

- Ambient Light
- Orientation
- Accelerometer
- Gyroscope
- Linear Acceleration
- Gravity
- Game Rotation Vector
- Pose
- Proximity
- Magnetometer
- Barometer
- Ambient Temperature
- GPS / GNSS
- Microphone
- NFC

---

# Privacy

Your privacy is a core design principle of nikki streams.

- All communication happens within your local network by default.
- No cloud service is required to use the SDK.
- Sensor data remains on your own network.
- You control which applications connect to your device.
- Your phone remains your device, and your data remains yours.

nikki streams is designed for experimentation, learning, rapid prototyping, automation, and creative projects while keeping your personal data private.

---

# Learn More

To get the most out of nikki streams, explore the official resources:

- 📖 Documentation
- 🎥 Video Tutorials
- 💡 Example Projects
- 🚀 Quick Start Guides

These resources cover installation, sensor streaming, automation, IoT projects, and real-world examples.

GitHub Repository:

https://github.com/nikki-build/streams.python

---

# Requirements

- Python 3.10+
- nikki streams mobile application
- Device and computer connected to the same local network

---

# License

MIT License

---

Happy Building! 🚀
