Mashov

April 18, 2026 · View on GitHub

Unofficial integration for משו"ב (Mashov) that logs into the student portal and exposes data as sensors:

  • Weekly Plan
  • Homework
  • Behavior
  • Timetable (weekly timetable per student)
  • Lessons History (historical lessons/logs per student)
  • Global Holidays (school holidays calendar)

This project is community-made and not affiliated with Mashov. Use at your own risk and follow your school's policies.

🧩 Features

  • Simple Config Flow (UI) via Settings → Devices & Services → Add Integration → Mashov.
  • Daily refresh (02:30 by default) + mashov.refresh_now service for on-demand updates.
  • Sensors expose compact state (count) + rich attributes (lists you can use in automations / dashboards).
  • Calendar entity for school holidays - integrates with Home Assistant calendar view 📅
  • Diagnostics endpoint for safe issue reporting (redacts credentials).

📦 Installation

  1. Open HACS → Integrations → ⋯ → Custom repositories.
  2. Add repository URL: https://github.com/NirBY/ha-mashov. Select Category: Integration.
  3. Search for Mashov in HACS, install, and Restart Home Assistant.

Manual

  1. Copy custom_components/mashov into your HA /config/ folder.
  2. Restart Home Assistant.

The integration includes custom icon.png and logo.png for better visuals in Home Assistant.

⚙️ Configuration

  1. Add Integration → Mashov.
  2. Enter username / password.
  3. Pick your school from the dropdown with fast autocomplete (type to filter). If the list doesn't load, a text field appears; type the school name in Hebrew or the Semel and we'll resolve it.
  4. Done — sensors for each child will be created.

Options

To configure options, go to: Settings → Devices & Services → Mashov → Configure

Credential updates in Configure apply only to the specific Mashov hub entry you opened. If you have multiple Mashov hubs, updating one hub's username or password does not automatically update the others.

  • Homework window: days back (default 7), days forward (default 21)
  • Daily refresh time: default 02:30
  • API base: default https://web.mashov.info/api/ (override if your deployment differs)
  • Max items in attributes: maximum items to store in sensor attributes (default 100, range: 10-500)
    • Controls how many recent items are stored in sensor attributes to prevent database size issues
    • Sensors automatically clean technical fields and limit size to fit within Home Assistant's 16KB limit
    • Full data is always available via coordinator.data for advanced automations
    • Attributes show total_items (all available) and stored_items (actually stored in attributes)

Important note about night-time polling

  • Pulling data at night may trigger email notifications from Mashov about account activity/logins. If this is undesirable:
    • Prefer scheduling the daily/weekly refresh to daytime hours (e.g., 14:00).
    • Use the Options screen or YAML to set schedule_type and schedule_time accordingly.
    • Avoid long-running interval mode during overnight hours.

Configuration via configuration.yaml (optional)

You can also configure the refresh schedule via YAML. Values in YAML override the Options UI.

mashov:
  # Scheduling
  schedule_type: daily        # daily | weekly | interval
  schedule_time: "14:00"      # for daily/weekly
  schedule_day: 0             # 0=Monday ... 6=Sunday
  schedule_days: [0, 2, 4]    # optional multiple days for weekly
  schedule_interval: 120      # minutes (for interval mode)

  # Other (optional)
  homework_days_back: 7
  homework_days_forward: 21
  api_base: "https://web.mashov.info/api/"
  max_items_in_attributes: 100  # 10-500, limits items stored in DB

🧠 Entities (per child)

For each child N, these sensors are created:

  • Weekly Plan – sensor.mashov_<student_id>_weekly_plan
  • Homework – sensor.mashov_<student_id>_homework
  • Behavior – sensor.mashov_<student_id>_behavior
  • Timetable – sensor.mashov_<student_id>_timetable
  • Lessons History – sensor.mashov_<student_id>_lessons_history
  • Grades – sensor.mashov_<student_id>_grades – 🆕 New in v1.0.3

State = number of items.
Attributes (common): items, formatted_summary, formatted_by_date, formatted_by_subject (and for timetable: also table helpers).

Tip: Use {{ state_attr('sensor.mashov_<id>_homework', 'items') }} to access raw lists.

Note: The items attribute contains cleaned, size-optimized recent items (technical fields removed). To see all items:

  • total_items = total number of items available
  • stored_items = number of items in the items attribute
  • Full raw data is always available via coordinator.data for advanced automations

Global Entities

  • Holidays Sensor – sensor.mashov_holidays
    State = number of holidays. Attributes: items, formatted_summary, formatted_by_date.

  • Holidays Calendar – calendar.mashov_holidays_calendar – 🆕 New in v1.0.3
    Full calendar integration for school holidays. Shows events in Home Assistant calendar view with start/end dates.
    Contributed by @aviadlevy

🔔 Automation Blueprint: Daily Homework & Behavior Announcement

A ready-to-use blueprint that speaks today's homework and behavior in Hebrew at a fixed time, with safe defaults and volume handling.

One‑click import (My Home Assistant):

Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint URL.

If you hit a cache issue when importing, use the commit‑pinned link:

Import pinned version

Blueprint file location: blueprints/automation/mashov/mashov_daily_homework_announce.yaml.

What does it do?

  • Daily voice announcement at 15:00 that reads the student’s name, today’s behaviors, and today’s homework (Hebrew).
  • Runs only in daytime and skips holidays using your Mashov holidays sensor (Items[start/end]).
  • Triggers only if there is data for today in the homework and/or behavior sensors.
  • Temporarily sets the speaker to max volume, speaks via tts.speak (configurable), then restores the original volume after playback.
  • Works with any media_player (Sonos, Nest, etc.); volume restore is state-aware.
  • Fully templated blueprint: select your own Mashov sensors and speaker at import time.
  • Safe defaults: 15:00 schedule, Hebrew (he-IL) TTS, 07:00–22:00 guard rails.
  • GitHub-friendly: no hardcoded entity IDs; can be imported with a My Home Assistant one-click link.

How to use

  1. Click the import button above and select your holiday_sensor, homework_sensor, behavior_sensor, media_player, and optional tts_service.
  2. Save the automation. By default it runs every day at 15:00.

🎒 Automation Blueprint: Bag Reminder (Tomorrow's Subjects)

One‑click import (My Home Assistant):

Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint URL.

What does it do?

  • Runs once daily at 18:00 to help a student pack their school bag for tomorrow.
  • Skips automatically if it’s night-time, Saturday, or a listed holiday (from the holiday sensor).
  • Reads tomorrow’s subjects only when timetable data actually exists for tomorrow.
  • Builds a Hebrew TTS message: “שלום {Student}… אנא לסדר תיק למחר… {subjects + teacher names [+ plan]}”.
  • Temporarily raises the speaker to a configurable max volume, then restores the previous (or fallback) volume after TTS ends.
  • Pulls subjects and teacher names from the Mashov timetable; optionally appends each lesson’s “plan” from the weekly plan sensor.
  • Waits for the speaker state to finish playing before restoring volume, to avoid cutting the message.
  • Provides rich trace/log lines explaining why it ran or skipped (night block, Saturday, holiday, has data).

Blueprint file location: blueprints/automation/mashov/bag_reminder_tomorrow.yaml.

How to use

  1. Click the import button above, pick your Mashov timetable sensor, (optional) weekly plan sensor, holiday sensor, media player and voice settings.
  2. Save the automation. Defaults: 18:00, Hebrew, night guard 22:00–07:00.

🛠️ Services

mashov.refresh_now

Trigger an immediate refresh.

service: mashov.refresh_now
data:
  entry_id: YOUR_ENTRY_ID  # optional; if omitted, all entries refresh

Calling without entry_id refreshes all configured Mashov hubs.

🧱 Lovelace Cards (Examples)

You can quickly add cards to display Mashov data. Use !include to import ready-made cards.

Files:

  • examples/lovelace/cards/weekly_plan_table_advanced.yaml
  • examples/lovelace/cards/behavior_list_by_date.yaml
  • examples/lovelace/cards/homework_list_by_date.yaml
  • examples/lovelace/cards/refresh_all_button.yaml

Copy these files into your Home Assistant config at /config/lovelace/cards/examples/, then reference them like this:

Note: HACS installs only custom_components/. Copy the example card files to your /config/examples/ (or paste the YAML into UI cards) if you want to use !include.

Advanced weekly plan (table) via include:

views:
  - title: Mashov
    cards:
      - !include lovelace/cards/examples/weekly_plan_table_advanced.yaml

Example preview:

Weekly timetable + plan + holidays

Behavior events grouped by date:

views:
  - title: Mashov
    cards:
      - !include lovelace/cards/examples/behavior_list_by_date.yaml

Example preview:

Behavior grouped by date

Homework grouped by date:

views:
  - title: Mashov
    cards:
      - !include lovelace/cards/examples/homework_list_by_date.yaml

Example preview:

Homework grouped by date

Refresh all hubs button:

views:
  - title: Mashov
    cards:
      - !include lovelace/cards/examples/refresh_all_button.yaml

🔍 Troubleshooting

  • 401 / 403: re-check credentials and school choice. Try Reconfigure or Remove & Add the integration again.
  • Different host: open Options → API base and paste the base prefix you see in your browser DevTools Network tab (up to /api/).
    Common defaults: https://web.mashov.info/api/, sometimes https://mobileapi.mashov.info/api/.
  • No schools in dropdown: temporary catalog issue — the flow falls back to text; enter the name or Semel to resolve.
  • Autocomplete not working: the dropdown is limited to 200 schools for performance; try typing the school name to filter the list.
  • Multiple kids missing: ensure your account actually lists multiple students in Mashov. Check HA logs for custom_components.mashov debug entries.
  • Session errors: if you see "Unclosed client session" errors, restart Home Assistant to clear any stale connections.
  • "New Device" emails: v1.0.5+ includes session persistence to prevent repetitive "New Device login" emails. If you still receive them, ensure the integration is not being restarted too frequently (e.g., watchlists or full system restarts) and that custom_components.mashov.cache exists in .storage.

Enable debug logs

logger:
  logs:
    custom_components.mashov: debug

🔐 Privacy & Security

  • Credentials are stored by Home Assistant in the config entry store.
  • The integration mirrors the Mashov web client behavior (headers, cookies, API calls). Endpoints may change without notice.
  • Before sharing logs, screenshots, or diagnostics in GitHub issues, review them and remove personal data such as usernames, student names, IDs, grades, homework text, session cookies, tokens, phone numbers, email addresses, and any other sensitive school or account details.
  • If you are unsure whether something is safe to share, redact it first. Only upload the minimum data needed to reproduce the problem.

📄 License

MIT © 2025

📜 Changelog

See the full changelog in CHANGELOG.md.